Spotify MCP

SpotifyMCP

Spotify Web API MCP: playback, library, playlists, search, podcasts. Not affiliated with Spotify.

A broad Spotify Web API tool surface, plus extras most servers skip. Registration-gated wrappers are explained rather than hidden; see Registration-gated endpoints for the generated list.

What you get by default, and what to do about the rest. A server started with no environment registers a curated surface — search, playback, playlists, library, following — sized so the tool list does not dominate the context window before you have typed anything. SPOTIFY_MCP_TOOLSETS=all registers the entire registry instead, and the stats.fm tools are opt-in with SPOTIFY_MCP_STATSFM=1. Both are one line in docs/configuration.md.

A server started with no SPOTIFY_MCP_TOOLSETS registers 131 tools (150,111 bytes of schema) — the curated default surface (#889). SPOTIFY_MCP_TOOLSETS=all registers all 562 tools, along with 17 fixed resources, 28 resource templates, and 14 prompts. Toolsets and production gates can trim a configured host further; both figures describe a real production tools/list after finalizers.

3.0 and later

3.0 was the release where the open issue list went to zero — every epic, every issue under it, every contradiction we turned up auditing ourselves. Most of that backlog was never "bugs" in the crashing sense; it was places where this server reported a value it had not actually checked, which is the only kind of wrong that is genuinely dangerous.

It also *removed* tools, because Spotify deleted the endpoints underneath them in February 2026 — including artist follows, which have no migration target at all.

→ [Read the 3.0 roadmap](docs/v3-roadmap.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.

⚠️ Never paste your Spotify credentials into a chat. Spotify's Developer Terms treat the Client ID as a credential: §VI.1.1 groups "I.D.s, client I.D.s, keys, passwords, security codes, or tokens" together as *Security Codes*, §VI.1.3 forbids disclosing them to any other party, and §VI.1.4 makes you responsible for their confidentiality. Anything you type into a conversation is retained by the model provider, written to shell history, and carried in the agent's context window. The Client ID is the only credential this server needs, and it is a *Security Code* rather than a public identifier — treat it like a password.

`

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. Point me at where the dashboard

shows the Client ID, then stop — I will copy it myself.

2. Clone and build:

git clone https://github.com/NovaLux12/spotify-mcp-server.git

cd spotify-mcp-server && npm ci && npm run build

3. Show me which file my MCP host reads server environment from. The host's server

config is the one that always works; a local .env is read only when you launch

through this repo's npm run dev or npm start, which pass --env-file-if-exists

on Node >=22.9 — the published binary does not read it. Print the exact line to

add. I will type the Client ID in myself. Do not ask me for it and never echo

it back.

4. Start the server and run the auth command yourself, then finish the browser login

when it opens. This server uses PKCE, so there is no client secret and no

credential to fetch beyond the Client ID.

5. Verify with the read-only spotify_doctor tool and report its rows.

`

---

Why this one

Quick start

1. Create a Spotify app

Spotify Developer Dashboard → Create app → add this Redirect URI exactly:

http://127.0.0.1:8888/callback

Copy the Client ID.

2. Authenticate

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.

Windows & headless

Windows (Command Prompt):

set SPOTIFY_CLIENT_ID=your_client_id_here && npx -y @novalux12/spotify-mcp@latest auth

Windows (PowerShell):

$env:SPOTIFY_CLIENT_ID="your_client_id_here"; npx -y @novalux12/spotify-mcp@latest auth

Windows is supported for install and everyday use, and is not covered by CI.

The commands above are the supported path, but the test suite runs on Linux

only, so a Windows-specific regression would not be caught before release.

See docs/platform-support.md for exactly what is

and is not verified there, and what the known gaps are.

Headless / remote host:

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.

3. Add to your MCP host

{

"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.

Claude Code · OpenClaw · other hosts

Claude Code (no JSON editing):

claude mcp add spotify -- npx -y @novalux12/spotify-mcp@latest

export SPOTIFY_CLIENT_ID=your_client_id_here

OpenClaw — ~/.openclaw/openclaw.json → mcp.servers:

"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.

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"
• "What does my taste look like? Build a playlist from it"
• "Do my stats.fm lifetime genres match what I've played this month?"

Configuration

All via env vars — no config file. Only SPOTIFY_CLIENT_ID is required.

Full reference: docs/configuration.md

spotify_doctor (CLI + in-server tool) diagnoses token state, scope gaps, Premium gating, rate-limit cooldowns, request/quota usage (cumulative + rolling-window counts, #904), and read-cache pressure (entries held, bytes retained, responses too large to cache, #894) without extra setup.

Upgrading to 2.0

2.0 is a contract release. One tool name is gone, four things moved, and one guarantee tightened:

1. `get_show_episodes` is removed. Use list_show_episodes (same endpoint, same arguments, minus the drifted alias). It was the only name that changed; everything else in the surface keeps its name. The exact registry totals are generated at the top of this file, so this sentence deliberately carries no count of its own to fall behind.

1. Destructive writes fail closed. Any confirmation-gated bulk write now refuses when the client cannot elicit, instead of proceeding unprompted. archive_played_episodes's confirm: true no longer authorises the delete (it is still accepted, and every result says it was ignored). For headless automation, set SPOTIFY_MCP_CONFIRM=never deliberately.
2. Playlist set-operation inputs are canonical. A/B pairs are playlist_a/playlist_b; ordered lists are playlists; playlist_subtract takes the base as base_playlist_id. This was the 2.0 contract; the old spellings it was allowed to keep alongside it were withdrawn in 3.0 (#1287). They are no longer in any tool's schema, and a call that still sends one is refused before any Spotify request with a validation error whose reason is retired_input, naming both what was sent and what to send instead. Each tool declared exactly one alias pair or one alias list, so the table below is a per-tool migration map rather than a bundle:

| ordered list | playlists