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

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.

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

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

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

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 mcp add spotify -- npx -y @novalux12/spotify-mcp@latest
export SPOTIFY_CLIENT_ID=your_client_id_here

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

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

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.

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.