{
  "markdown": "# spotify-mcp\n\n[![npm](https://img.shields.io/npm/v/%40xavifabregat%2Fspotify-mcp)](https://www.npmjs.com/package/@xavifabregat/spotify-mcp)\n[![CI](https://github.com/XavierFabregat/spotify-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/XavierFabregat/spotify-mcp/actions/workflows/ci.yml)\n[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)\n![node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen)\n\nControl Spotify by talking to your AI. An MCP server for Claude Desktop, Claude Code,\nCursor, and any other MCP client.\n\n> **You:** play something like early Bill Evans\n> **AI:** ▶ Now playing: *\"Peace Piece\" — Bill Evans · Everybody Digs Bill Evans*\n>\n> **You:** perfect, queue the whole album and save this one\n> **AI:** ➕ Queued *Everybody Digs Bill Evans* · ❤️ Saved \"Peace Piece\" to your library\n\nBuilt against the **current (post-February-2026) Spotify Web API** — many older\nSpotify MCP servers predate those changes and are partially broken.\n\n## Requirements\n\n- **Spotify Premium** — Spotify requires it for playback control and (since Feb 2026)\n  for creating the developer app you'll use.\n- **Node.js ≥ 20**\n\n## Quick start\n\n```sh\nnpx -y @xavifabregat/spotify-mcp init\n```\n\nThe wizard walks you through creating your own (free) Spotify developer app, asks for\nits Client ID, and opens a browser to connect your account — about 2 minutes total.\n\nWhy your own app? Spotify caps third-party apps at a handful of users, so every user\nbrings their own; the wizard makes that painless. No client secret is involved (PKCE).\nTokens stay in `~/.spotify-mcp/` on your machine and refresh silently.\n\nThe one detail that must be exact — your app's Redirect URI:\n\n```\nhttp://127.0.0.1:8888/callback\n```\n\n### Add to your MCP client\n\n**Claude Code**\n\n```sh\nclaude mcp add -s user spotify -- npx -y @xavifabregat/spotify-mcp\n```\n\n**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`)\nor **Cursor** (`~/.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"spotify\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@xavifabregat/spotify-mcp\"]\n    }\n  }\n}\n```\n\nRestart the client and start talking.\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `play` | Play by free-text query (search → best match → play) or Spotify URI |\n| `playback` | pause / resume / next / previous / seek / volume / shuffle / repeat |\n| `now_playing` | Current track, progress, device, mode |\n| `queue` | Add a track to the queue; show up next |\n| `devices` | List devices; transfer playback |\n| `search` | Browse tracks/albums/artists/playlists (max 10 per type — API cap) |\n| `get_playlists` | List your playlists |\n| `get_playlist_items` | Show a playlist's tracks (own/collaborative only — API restriction) |\n| `modify_playlist` | Create a playlist; add tracks |\n| `library` | Save / remove / check items in your library |\n| `authenticate` | Run the Spotify login from inside a conversation |\n\n## Design\n\n- **Tools are intents, not endpoints.** \"Play some Radiohead\" is one tool call —\n  the server searches, picks the best match, starts playback, and reports what it\n  chose so you can correct it. No search → choose → play round trips.\n- **Small surface.** 11 tools instead of one per API endpoint keeps tool selection\n  accurate across different AI clients and context lean.\n- **Responses are compact text with Spotify URIs**, so follow-ups (\"queue that\")\n  chain without re-searching. Raw API payloads never reach the model.\n- **Errors are instructions.** No active device? The response lists your devices and\n  says how to pick one. Not logged in? It points at the `authenticate` tool. The\n  model relays the fix instead of a stack trace.\n\n## Troubleshooting\n\n- **\"No active Spotify device\"** — Spotify's API can only steer a running app. Open\n  Spotify anywhere; if it just woke up, tap play/pause once. With exactly one device\n  online, the tools target it automatically.\n- **`INVALID_CLIENT: Invalid redirect URI` during login** — the Redirect URI in your\n  app settings isn't exactly `http://127.0.0.1:8888/callback` (`localhost` is\n  rejected by Spotify).\n- **Port 8888 in use during login** — set `SPOTIFY_REDIRECT_PORT` to a free port and\n  register the matching redirect URI.\n- **\"Token refresh failed\"** — run `npx -y @xavifabregat/spotify-mcp auth` to log in\n  again (e.g. after changing the Client ID).\n- **Config precedence** — the `SPOTIFY_CLIENT_ID` env var overrides\n  `~/.spotify-mcp/config.json` (written by `init`).\n\n## Development\n\n```sh\ngit clone https://github.com/XavierFabregat/spotify-mcp.git\ncd spotify-mcp\nnpm install\nnpm run build\nnpm run inspect   # MCP Inspector against the local build\n```\n\nLayout: `src/auth.ts` (OAuth PKCE + token store) · `src/spotify.ts` (typed API\nclient) · `src/tools/` (tool implementations) · `src/format.ts` (compact output).\n\n## License\n\nMIT © Xavi Fabregat\n",
  "bytes": 4864,
  "sha": "84bc723b41533801093ada4110b92171d48dd06f176a8a33649875a7dc0e8c92",
  "repo_slug": "xavierfabregat/spotify-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_xavierfabregat_spotify_mcp_488dc043/readme"
}