{
  "markdown": "# SpotifyMCP\n\n[![CI](https://github.com/NovaLux12/spotify-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/NovaLux12/spotify-mcp-server/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/@novalux12/spotify-mcp)](https://www.npmjs.com/package/@novalux12/spotify-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n![Node](https://img.shields.io/badge/node-%3E%3D22.9-brightgreen)\n\nAn 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.\n\n589 tools. Every non-deprecated endpoint, plus extras most servers skip. [Full list →](SPEC.md)\n\n---\n\n> ### 🤖 Paste this to your agent\n>\n> Copy the block below into Claude Code, Cursor, OpenClaw, or any coding agent — it will set SpotifyMCP up for you.\n>\n> ```\n> Set up the Spotify MCP server from https://github.com/NovaLux12/spotify-mcp-server.\n>\n> 1. Walk me through creating a Spotify app at https://developer.spotify.com/dashboard\n>    with redirect URI http://127.0.0.1:8888/callback, or use the Client ID I paste below.\n> 2. Clone, build, and authenticate:\n>    git clone https://github.com/NovaLux12/spotify-mcp-server.git\n>    cd spotify-mcp-server && npm ci && npm run build\n>    SPOTIFY_CLIENT_ID=<paste-here> npm run auth\n> 3. Wire it into my MCP host config and verify with the get_me tool.\n>\n> My Spotify Client ID: <paste here or say \"help me create one\">\n> ```\n\n---\n\n## Why this one\n\n| | |\n|---|---|\n| **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. |\n| **Safe** | `dry_run` previews on every write, receipts that prove what landed, human confirmation for bulk deletes, and `READONLY` to hide all writes. |\n| **Honest** | No zombie tools for endpoints Spotify removed. Legacy lookups explain the 403 instead of crashing. |\n| **Polished** | Paginated (up to 500), podcasts first-class, device-aware playback, `spotify_doctor` self-diagnosis, real test suite. |\n\n## Quick start\n\n### 1. Create a Spotify app\n\n[Spotify Developer Dashboard](https://developer.spotify.com/dashboard) → Create app → add this Redirect URI exactly:\n\n```\nhttp://127.0.0.1:8888/callback\n```\n\nCopy the **Client ID**.\n\n### 2. Authenticate\n\n```bash\nSPOTIFY_CLIENT_ID=your_client_id_here npx -y @novalux12/spotify-mcp@latest auth\n```\n\nOpens a browser, saves tokens to `~/.spotify-mcp/tokens.json`, auto-refreshes after.\n\n<details><summary>Windows & headless</summary>\n\n**Windows (Command Prompt):**\n```cmd\nset SPOTIFY_CLIENT_ID=your_client_id_here && npx -y @novalux12/spotify-mcp@latest auth\n```\n\n**Windows (PowerShell):**\n```powershell\n$env:SPOTIFY_CLIENT_ID=\"your_client_id_here\"; npx -y @novalux12/spotify-mcp@latest auth\n```\n\n**Headless / remote host:**\n```bash\nSPOTIFY_HEADLESS=1 SPOTIFY_CLIENT_ID=your_client_id_here npx -y @novalux12/spotify-mcp@latest auth\n# prints a URL → open it on any machine → paste the redirect back\n```\n\nCheck: `npx -y @novalux12/spotify-mcp@latest doctor` — exit 0 means you're good.\n\n</details>\n\n### 3. Add to your MCP host\n\n```json\n{\n  \"mcpServers\": {\n    \"spotify\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@novalux12/spotify-mcp@latest\"],\n      \"env\": { \"SPOTIFY_CLIENT_ID\": \"your_client_id_here\" }\n    }\n  }\n}\n```\n\nRestart the host. A hammer icon in the chat input means it's connected.\n\n<details><summary>Claude Code · OpenClaw · other hosts</summary>\n\n**Claude Code (no JSON editing):**\n```bash\nclaude mcp add spotify -- npx -y @novalux12/spotify-mcp@latest\nexport SPOTIFY_CLIENT_ID=your_client_id_here\n```\n\n**OpenClaw** — `~/.openclaw/openclaw.json` → `mcp.servers`:\n```json\n\"spotify\": {\n  \"command\": \"node\",\n  \"args\": [\"/path/to/spotify-mcp-server/dist/index.js\"],\n  \"cwd\": \"/path/to/spotify-mcp-server\",\n  \"env\": { \"SPOTIFY_CLIENT_ID\": \"your_client_id_here\" }\n}\n```\n\nAny 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.\n\n</details>\n\n## What you can ask\n\n- \"What are my top tracks this month?\"\n- \"Make a late-night driving playlist\"\n- \"Add Blinding Lights to my workout playlist\"\n- \"What podcasts have new episodes?\"\n- \"Clean duplicates across all my playlists\"\n- \"What does my taste look like? Build a playlist from it\"\n- \"Do my stats.fm lifetime genres match what I've played this month?\"\n\n## Configuration\n\nAll via env vars — no config file. Only `SPOTIFY_CLIENT_ID` is required.\n\n| Variable | Example | Purpose |\n|---|---|---|\n| `SPOTIFY_MCP_TOOLSETS` | `playback,catalog` | Trim by group for hosts that cap tool counts |\n| `SPOTIFY_MCP_READONLY` | `1` | Hide every write tool |\n| `SPOTIFY_MCP_HISTORY` | `1` | Log mutations to JSONL for undo |\n\nFull reference: [docs/configuration.md](docs/configuration.md)\n\n`spotify_doctor` (CLI + in-server tool) diagnoses token state, scope gaps, Premium gating, and rate-limit cooldowns without extra setup.\n\n## Docs\n\n- [SPEC.md](SPEC.md) — every tool, resource & prompt\n- [ARCHITECTURE.md](ARCHITECTURE.md) — how it's built\n- [docs/configuration.md](docs/configuration.md) — all env vars\n- [docs/statsfm.md](docs/statsfm.md) — stats.fm second source: setup, tool cheat sheet, gotchas\n- [docs/cookbook.md](docs/cookbook.md) — ten copy-paste agent recipes\n- [docs/taste.md](docs/taste.md) — anonymized taste showcase driving a playlist\n- [docs/faq.md](docs/faq.md) — auth, Premium, 403s, headless, tokens\n- [CONTRIBUTING.md](CONTRIBUTING.md) — dev setup & conventions\n- [CHANGELOG.md](CHANGELOG.md) — release history\n\n## Requirements\n\n- **Premium** for playback control (play/pause/skip/seek/volume/queue). Free accounts can still use search, library & playlists.\n- Node 22.9+, Spotify app in dev mode (5 users until extended quota).\n- Audiobooks gated by Spotify to US/UK/CA/IE/NZ/AU.\n- A subset of endpoints is **registration-gated** — 403 on current app registrations regardless of scopes or Premium. See [Registration-gated endpoints](#registration-gated-endpoints).\n\n### Registration-gated endpoints\n\nSome 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](https://github.com/NovaLux12/spotify-mcp-server/issues/329)):\n\n| Response | Endpoints |\n|---|---|\n| `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` |\n| `404 Not Found` | `/recommendations`, `/recommendations/available-genre-seeds` |\n| `410 Gone` | `/me/apps`, `/me/chapters` |\n\nNotes:\n\n- 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.\n- The undocumented `/me/library/contains` check is *not* gated (it returned 200 on the same probe) and powers the duplicate-cleanup tooling.\n- 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.\n\n<details><summary>Troubleshooting</summary>\n\n- **\"Not authenticated\"** → re-run `auth`; check `~/.spotify-mcp/tokens.json` exists and the redirect URI matches exactly (no trailing slash).\n- **Auth loop / S256 error** → open a private window, log into spotify.com first, then retry the auth URL there.\n- **Port in use (8888)** → free the port, set `SPOTIFY_REDIRECT_URI` to another port, or use `SPOTIFY_HEADLESS=1`.\n- **\"Premium required\"** on playback → expected on Free accounts; no workaround.\n- **`Forbidden` on lookup tools** (categories, markets, top-tracks, user profiles, library `contains` checks) → these endpoints are registration-gated by Spotify; see [Registration-gated endpoints](#registration-gated-endpoints).\n- **Still stuck?** `npx -y @novalux12/spotify-mcp@latest doctor` or ask your agent to run the [spotify-mcp-doctor skill](skills/spotify-mcp-doctor/SKILL.md).\n\n</details>\n\n## Development\n\n```bash\ngit clone https://github.com/NovaLux12/spotify-mcp-server.git && cd spotify-mcp-server\nnpm ci && npm run build\ncp .env.example .env  # add your Client ID\nnpm run auth          # one-time login\nnpm run dev           # run from source\nnpm test              # unit + MCP smoke tests\n```\n\n---\n\n*Not affiliated with Spotify. Use per the [Spotify Developer Terms](https://developer.spotify.com/terms).*\n\n[MIT](LICENSE) © Carme99 and NovaLux12 contributors · Acknowledges [calebWei/SpotifyMCP](https://github.com/calebWei/SpotifyMCP) and [varunneal/spotify-mcp](https://github.com/varunneal/spotify-mcp).\n",
  "bytes": 9219,
  "sha": "793331718350a097c6b0ee51632bda080ad9084c59206013753d4b561bdf307d",
  "repo_slug": "novalux12/spotify-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_novalux12_spotify_mcp_server_8fdf8afe/readme"
}