Spotify MCP Server

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.

550 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

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

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"

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, 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
• 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):

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.

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