Spotify MCP
The most complete Spotify MCP: playback, library, playlists, search, podcasts and audiobooks.
Open source Open in the app JSON README (API)
About
The most complete Spotify MCP: playback, library, playlists, search, podcasts and audiobooks.
Details
- Kind
- MCP servers
- Topic
- Media, design & games
- Publisher
- novalux12
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.29.0
- Stars
- 1
- Last push
- 2026-09-04T22:26:50Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:08
- Updated
- 2026-09-05 22:00:23
- Origin id
io.github.NovaLux12/spotify-mcp-server
README
# SpotifyMCP
[](https://github.com/NovaLux12/spotify-mcp-server/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@novalux12/spotify-mcp)
[](LICENSE)
An MCP server that wraps the Spotify Web API — lets Claude and other AI assistants control playback, search the catalog (tracks, podcasts, audiobooks), and manage your library and playlists.
551 tools. Every non-deprecated endpoint, plus extras most servers skip. [Full list →](SPEC.md)
---
> ### 🤖 Paste this to your agent
>
> Copy the block below into Claude Code, Cursor, OpenClaw, or any coding agent — it will set SpotifyMCP up for you.
>
> ```
> Set up the Spotify MCP server from https://github.com/NovaLux12/spotify-mcp-server.
>
> 1. Walk me through creating a Spotify app at https://developer.spotify.com/dashboard
> with redirect URI http://127.0.0.1:8888/callback, or use the Client ID I paste below.
> 2. Clone, build, and authenticate:
> git clone https://github.com/NovaLux12/spotify-mcp-server.git
> cd spotify-mcp-server && npm ci && npm run build
> SPOTIFY_CLIENT_ID=<paste-here> npm run auth
> 3. Wire it into my MCP host config and verify with the get_me tool.
>
> My Spotify Client ID: <paste here or say "help me create one">
> ```
---
## Why this one
| | |
|---|---|
| **Complete** | 551 tools — playback, search, catalog, library, playlists, following + extras like duplicate cleanup, M3U/CSV import-export, podcast sessions, snapshot diffing, listening analytics and market checks. |
| **Safe** | `dry_run` previews on every write, receipts that prove what landed, human confirmation for bulk deletes, and `READONLY` to hide all writes. |
| **Honest** | No zombie tools for endpoints Spotify removed. Legacy lookups explain the 403 instead of crashing. |
| **Polished** | Paginated (up to 500), podcasts first-class, device-aware playback, `spotify_doctor` self-diagnosis, real test suite. |
## Quick start
### 1. Create a Spotify app
[Spotify Developer Dashboard](https://developer.spotify.com/dashboard) → Create app → add this Redirect URI exactly:
```
http://127.0.0.1:8888/callback
```
Copy the **Client ID**.
### 2. Authenticate
```bash
SPOTIFY_CLIENT_ID=your_client_id_here npx -y @novalux12/spotify-mcp@latest auth
```
Opens a browser, saves tokens to `~/.spotify-mcp/tokens.json`, auto-refreshes after.
<details><summary>Windows & headless</summary>
**Windows (Command Prompt):**
```cmd
set SPOTIFY_CLIENT_ID=your_client_id_here && npx -y @novalux12/spotify-mcp@latest auth
```
**Windows (PowerShell):**
```powershell
$env:SPOTIFY_CLIENT_ID="your_client_id_here"; npx -y @novalux12/spotify-mcp@latest auth
```
**Headless / remote host:**
```bash
SPOTIFY_HEADLESS=1 SPOTIFY_CLIENT_ID=your_client_id_here npx -y @novalux12/spotify-mcp@latest auth
# prints a URL → open it on any machine → paste the redirect back
```
Check: `npx -y @novalux12/spotify-mcp@latest doctor` — exit 0 means you're good.
</details>
### 3. Add to your MCP host
```json
{
"mcpServers": {
"spotify": {
"command": "npx",
"args": ["-y", "@novalux12/spotify-mcp@latest"],
"env": { "SPOTIFY_CLIENT_ID": "your_client_id_here" }
}
}
}
```
Restart the host. A hammer icon in the chat input means it's connected.
<details><summary>Claude Code · OpenClaw · other hosts</summary>
**Claude Code (no JSON editing):**
```bash
claude mcp add spotify -- npx -y @novalux12/spotify-mcp@latest
export SPOTIFY_CLIENT_ID=your_client_id_here
```
**OpenClaw** — `~/.openclaw/openclaw.json` → `mcp.servers`:
```json
"spotify": {
"command": "node",
"args": ["/path/to/spotify-mcp-server/dist/index.js"],
"cwd": "/path/to/spotify-mcp-server",
"env": { "SPOTIFY_CLIENT_ID": "your_client_id_here" }
}
```
Any spec-compliant host works — same `command`/`args`/`env` shape under `mcpServers` or `servers`. If the host can't pass env vars, authenticate once beforehand; the token cache persists.
</details>
## What you can ask
- "What are my top tracks this month?"
- "Make a late-night driving playlist"
- "Add Blinding Lights to my workout playlist"
- "What podcasts have new episodes?"
- "Clean duplicates across all my playlists"
## Configuration
All via env vars — no config file. Only `SPOTIFY_CLIENT_ID` is required.
| Variable | Example | Purpose |
|---|---|---|
| `SPOTIFY_MCP_TOOLSETS` | `playback,catalog` | Trim by group for hosts that cap tool counts |
| `SPOTIFY_MCP_READONLY` | `1` | Hide every write tool |
| `SPOTIFY_MCP_HISTORY` | `1` | Log mutations to JSONL for undo |
Full reference: [docs/configuration.md](docs/configuration.md)
`spotify_doctor` (CLI + in-server tool) diagnoses token state, scope gaps, Premium gating, and rate-limit cooldowns without extra setup.
## Docs
- [SPEC.md](SPEC.md) — every tool, resource & prompt
- [ARCHITECTURE.md](ARCHITECTURE.md) — how it's built
- [docs/configuration.md](docs/configuration.md) — all env vars
- [CONTRIBUTING.md](CONTRIBUTING.md) — dev setup & conventions
- [CHANGELOG.md](CHANGELOG.md) — release history
## Requirements
- **Premium** for playback control (play/pause/skip/seek/volume/queue). Free accounts can still use search, library & playlists.
- Node 22.9+, Spotify app in dev mode (5 users until extended quota).
- Audiobooks gated by Spotify to US/UK/CA/IE/NZ/AU.
- A subset of endpoints is **registration-gated** — 403 on current app registrations regardless of scopes or Premium. See [Registration-gated endpoints](#registration-gated-endpoints).
### Registration-gated endpoints
Some Web API endpoints are denied **at the app-registration level**: on current Spotify app registrations they return `403 Forbidden` no matter which OAuth scopes you grant or whether the account is Premium. This is Spotify-side gating, not a misconfiguration on your end. Verified by live probe on 2026-08-27 ([#329](https://github.com/NovaLux12/spotify-mcp-server/issues/329)):
| Response | Endpoints |
|---|---|
| `403 Forbidden` | `/browse/new-releases`, `/browse/categories` (and `/browse/categories/{id}/playlists`), `/markets`, `/artists/{id}/top-tracks`, `/users/{id}` (and `/users/{id}/playlists`), every documented `/me/{type}/contains` check (tracks, albums, shows, episodes, audiobooks, following), `/playlists/{id}/followers/contains` |
| `404 Not Found` | `/recommendations`, `/recommendations/available-genre-seeds` |
| `410 Gone` | `/me/apps`, `/me/chapters` |
Notes:
- Tools wrapping a gated endpoint are **not hidden** — they still work on legacy app registrations where Spotify granted the endpoint. On a newer registration you'll get the server's plain-English 403 explanation instead of a crash.
- The undocumented `/me/library/contains` check is *not* gated (it returned 200 on the same probe) and powers the duplicate-cleanup tooling.
- Legacy lookups the server already explains gracefully (audio-features, audio-analysis, related-artists, featured-playlists) also probe as 403; their tools say so in the error message.
<details><summary>Troubleshooting</summary>
- **"Not authenticated"** → re-run `auth`; check `~/.spotify-mcp/tokens.json` exists and the redirect URI matches exactly (no trailing slash).
- **Auth loop / S256 error** → open a private window, log into spotify.com first, then retry the auth URL there.
- **Port in use (8888)** → free the port, set `SPOTIFY_REDIRECT_URI` to another port, or use `SPOTIFY_HEADLESS=1`.
- **"Premium required"** on playback → expected on Free accounts; no workaround.
- **`Forbidden` on lookup tools** (categories, markets, top-tracks, user profiles, library `contains` checks) → these endpoints are registration-gated by Spotify; see [Registration-gated endpoints](#registration-gated-endpoints).
- **Still stuck?** `npx -y @novalux12/spotify-mcp@latest doctor` or ask your agent to run the [spotify-mcp-doctor skill](skills/spotify-mcp-doctor/SKILL.md).
</details>
## Development
```bash
git clone https://github.com/NovaLux12/spotify-mcp-server.git && cd spotify-mcp-server
npm ci && npm run build
cp .env.example .env # add your Client ID
npm run auth # one-time login
npm run dev # run from source
npm test # unit + MCP smoke tests
```
---
*Not affiliated with Spotify. Use per the [Spotify Developer Terms](https://developer.spotify.com/terms).*
[MIT](LICENSE) © Carme99 and NovaLux12 contributors · Acknowledges [calebWei/SpotifyMCP](https://github.com/calebWei/SpotifyMCP) and [varunneal/spotify-mcp](https://github.com/varunneal/spotify-mcp).