@novalux12/spotify-mcp

SpotifyMCP

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.

589 tools. Every non-deprecated endpoint, plus extras most servers skip. Full list →

🤖 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	589 tools — playback, search, catalog, library, playlists, following + extras like duplicate cleanup, M3U/CSV import-export, podcast sessions, snapshot diffing, listening analytics, market checks, and stats.fm taste imports.
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 → 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

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.

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

spotify_doctor (CLI + in-server tool) diagnoses token state, scope gaps, Premium gating, and rate-limit cooldowns without extra setup.

Docs

• SPEC.md — every tool, resource & prompt
• ARCHITECTURE.md — how it's built
• docs/configuration.md — all env vars
• docs/statsfm.md — stats.fm second source: setup, tool cheat sheet, gotchas
• docs/cookbook.md — ten copy-paste agent recipes
• docs/taste.md — anonymized taste showcase driving a playlist
• docs/faq.md — auth, Premium, 403s, headless, tokens
• 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. 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. Verified by live probe on 2026-08-27 (#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.

Troubleshooting

• "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.
• Still stuck? npx -y @novalux12/spotify-mcp@latest doctor or ask your agent to run the spotify-mcp-doctor skill.

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.