Spotify Web MCP Server

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 is landing

3.0 is the release where the open issue list goes 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 removes 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

---

🤖 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 (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 (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.

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

3. 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:

   family	canonical	the spelling that tool used to declare
   A/B pair	playlist_a, playlist_b	a/b, or playlist_id_a/playlist_id_b, or playlist_a_id/playlist_b_id — one of them, per tool
   ordered list	playlists	playlist_ids, or source_playlist_ids, or sources — one of them, per tool
   subtraction	base_playlist_id + playlists	subtract_playlist_ids, or the positional form playlists: [base, ...sources] — one of them, per tool

   base_playlist_id is required again: with the positional form gone there is no longer a base for a caller to omit. A name the tool does not declare, and is not a retired spelling, is an unknown_param error — a different claim from retired_input, which says the server published that name until 3.0.

4. Numeric caps have canonical names. max_results caps what is returned; limit and scan_cap cap how much of each source is read.

5. Unknown arguments are rejected with a typed unknown_param error rather than ignored, so a renamed parameter fails loudly instead of silently doing nothing.

Run spotify_doctor after upgrading: it reports the registered surface, the gates that hid modules, and the granted scopes in one call.

Docs

• docs/v3-roadmap.md — what's coming in 3.0, and the one bug underneath all of it
• docs/migration-v3.md — every retired name in 3.0 and what replaced it, including the one operation with no replacement
• SPEC.md — every tool, resource & prompt
• ARCHITECTURE.md — how it's built
• docs/configuration.md — all env vars
• docs/cli.md — tools, call, watch, export, init: the CLI as an MCP client
• docs/schema-budgets.md — per-module schema budgets and registration order
• docs/statsfm.md — stats.fm second source: setup, tool cheat sheet, gotchas
• docs/cookbook.md — copy-paste agent recipes
• docs/non-goals.md — what v2 will not do, why, and what it offers instead
• docs/taste.md — anonymized taste showcase driving a playlist
• docs/wave2-composites.md — read-only taste composites
• docs/distribution.md — distribution and release notes
• docs/faq.md — auth, Premium, 403s, headless, tokens
• docs/compliance.md — brand marks, attribution & the outbound User-Agent
• CONTRIBUTING.md — dev setup & conventions
• 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. Whether a grandfathered registration still answers 200 is unverified (#1338). This is a property of your app registration, not of the tool. See 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.

Nothing here is simply "removed". Three sources describe this class and they do not agree, which is why the table below states the runtime behaviour instead of a verdict:

• Spotify's February 2026 changelog marks a batch of operations [REMOVED].
• The live OpenAPI schema still publishes most of those same paths, carrying deprecated: true rather than deleting them — /artists/{id}/top-tracks and all seven Get Several batch paths among them.
• The runtime truth is neither document: it is what your app registration is allowed to read. A registration without the grant answers 403/404/410. Whether a grandfathered registration still answers 200 is unverified (#1338): no probe in this repository shows it, and the one probe artefact that was once cited for it records 403 on every such path.

So a 403 here is a property of the registration, not of the tool. No tool is hidden for being gated, no gated tool is a zombie: each one either reads a documented replacement and answers, or makes the call and explains the 403 in plain English. The authoritative list is the GATED_FAMILIES array in src/gating.ts — GATED_PATH_PATTERNS is derived from it, so the classifier and this table cannot drift apart.

All 8 families above are operations Spotify's February 2026 changelog marks [REMOVED].

Confirm the list yourself against the source of truth:

grep -n "id: '" src/gating.ts        # the families, with tools and fallback per row

Notes:

• A family in that list is a runtime classifier, not a promise that a tool calls it. Three families (browse-new-releases, me-type-contains, playlist-followers-contains) have no live call site left — the tools that used them were migrated onto replacements — and their patterns are retained so a future caller is still covered by the 403 contract rather than silently losing it.
• GET /me/library/contains is not gated (it returned 200 on the same probe) and backs the saved-state reads behind check_playlist_following, restore_library_snapshot and receipt verification. The contains families above are the documented per-type checks, which the changelog marks removed in favour of this one. (The playlist duplicate-cleanup tools are not in that set — they page /playlists/{id}/items.)
• Batch fallback (#725). When a Get Several batch endpoint answers 403, fetchSeveral retries through per-id GET /<kind>/{id} calls on the client's existing queue/backoff. Per-id paths are not in the gated class, so the read still succeeds. The response carries degraded: true and a [degraded: batch endpoint returned 403; … fetched individually] footer in prose, plus degraded_reason in structuredContent, so a caller can tell a per-item round-trip from a clean batch read.
• Endpoints Spotify lists as removed that this server does not wrap at all (no shipped tool, so nothing to explain): /recommendations, /recommendations/available-genre-seeds, /me/apps, /me/chapters, the /artists/{id}/related-artists, /audio-features, /audio-analysis and /browse/featured-playlists reads, and the /playlists/{id}/tracks family (superseded by /playlists/{id}/items). These are absent from the table above because absence of a tool is the honest answer for them — there is no 403 to explain.

• "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. The message names EADDRINUSE and the port because the usual cause is a previous auth still holding it.
• Timed out waiting for the browser callback → not a port conflict; the listener bound and has been closed. Retry, and check the redirect URI is registered exactly. Bound it with SPOTIFY_AUTH_TIMEOUT_MS (default 5 min).
• "Premium required" on playback → expected on Free accounts; no workaround.
• Forbidden on lookup tools (categories, markets, top-tracks, user profiles, the per-type contains checks) → these endpoints are registration-gated by Spotify; see Registration-gated endpoints. (GET /me/library/contains is not one of them, so a 403 there is a real problem, not a gated registration.)
• Still stuck? npx -y @novalux12/spotify-mcp@latest doctor or ask your agent to run the spotify-mcp-doctor skill.

What this server is not

v2 has a written non-goals list, so a request for something outside it gets an answer rather than a maybe. Each entry below carries its reasoning in SPEC §1, and docs/non-goals.md is the record behind both: what each one rules out, the source it rests on, and what the server offers instead.

• Audio streaming, audio analysis, and offline playback
• A web UI, a dashboard, or an MCP UI surface
• Multi-tenant or hosted operation
• Sharing one user's credentials across users
• Lyrics
• The Spotify Connect SDK and native client integration
• Voice control
• Training a model on Spotify data, or exporting derived profiles
• A second third-party upstream, ad-tech, or monetization egress
• Working around Spotify's own controls

Development

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.

MIT © Carme99 and NovaLux12 contributors · Acknowledges calebWei/SpotifyMCP and varunneal/spotify-mcp.