{
  "markdown": "# spotify-mcp MCP server\n\nmcp-name: io.github.jamiew/spotify-mcp\n\nMCP server connecting Claude with Spotify. This fork of [varunneal/spotify-mcp](https://github.com/varunneal/spotify-mcp) adds smart-batching tools and advanced playlist features that optimize API usage.\n\nThis one runs locally over stdio. If you want a **remote** MCP server instead — hosted, OAuth in the\nbrowser, no local install for the people connecting to it — see\n[jamiew/spotify-mcp-cloudflare](https://github.com/jamiew/spotify-mcp-cloudflare): a sibling Spotify\nMCP on Cloudflare Workers that you can deploy yourself in a few minutes, and a decent worked example\nof remote-MCP auth on Workers generally.\n\n## Features\n\n### Core Functionality\n- **Playback Control**: Start, pause, skip tracks, manage queue\n- **Search & Discovery**: Find tracks, albums, artists, playlists with pagination  \n- **Real-time State**: Live user profile and playback status\n- **Resources**: Read user, playback, track, playlist, artist, and album state by URI\n\n### Modern MCP Protocol\n- **Server instructions**: whole-surface guidance ships once per session instead of per tool\n- **Structured output**: every tool returns a typed schema, not a bare dict\n- **Tool annotations & icons**: read-only/destructive hints, titles, and a Spotify glyph\n- **Progress notifications**: live updates while paginating large playlists\n- **Elicitation**: destructive playlist removals ask for confirmation on clients that support it\n\n### Enhanced Playlist Tools (New in this fork)\n- **Smart Batch Operations**: Add/remove up to 100 tracks in single API calls\n- **Large Playlist Support**: Efficiently handle playlists with 1000+ tracks using pagination\n- **Advanced Playlist Management**: Create, modify details, reorder tracks, bulk track operations\n- **API-Optimized Workflows**: Intelligent batching reduces API calls by 60-80%\n\n### Tools\n| Tool | Does |\n| --- | --- |\n| `get_me` | The signed-in user's profile |\n| `search_music` | Search tracks, albums, artists or playlists, with filters |\n| `get_track_info` | Track details, batched up to 50 per call |\n| `get_artist_info` | Artist details plus their top tracks |\n| `get_album_info` | Album details plus its track list |\n| `get_playback_state` | What's playing now: track, device, progress, shuffle, repeat |\n| `control_playback` | Play, pause, next, previous, seek, volume, shuffle, repeat |\n| `list_devices` | Available Spotify Connect devices |\n| `transfer_playback` | Move playback to another device |\n| `get_queue` | Now playing plus the upcoming queue |\n| `add_to_queue` | Queue a track |\n| `get_user_playlists` | The user's playlists, paginated |\n| `get_playlist_info` | Playlist metadata without its tracks |\n| `get_playlist_tracks` | Playlist tracks, paginated to any size |\n| `create_playlist` | Create a playlist |\n| `modify_playlist_details` | Rename a playlist or change its description/visibility |\n| `add_tracks_to_playlist` | Add up to 100 tracks in one call |\n| `remove_tracks_from_playlist` | Remove tracks (confirms first where the client supports it) |\n| `reorder_playlist_tracks` | Move a block of tracks to a new position |\n| `unfollow_playlist` | Unfollow a playlist — how Spotify deletes your own |\n| `get_saved_tracks` | Liked Songs, paginated |\n| `save_tracks` | Like tracks |\n| `remove_saved_tracks` | Unlike tracks |\n| `get_top_items` | Top artists or tracks over a time range |\n| `get_recently_played` | Recently played tracks with timestamps |\n\n`tests/test_tool_metadata.py` fails if this table drifts from the code, or if a tool ships\nwithout a title, icon and behaviour annotations.\n\n## Installation\n\nRequires a Spotify **Premium** account and [`uv`](https://docs.astral.sh/uv/) >= 0.54.\n\n### 1. Get Spotify API keys\n\n1. Create an app at [developer.spotify.com/dashboard](https://developer.spotify.com/dashboard).\n2. Add redirect URI `http://127.0.0.1:8888` — it must match exactly what you set below.\n3. Copy the **Client ID** and **Client Secret**.\n\n### 2. Add the server to your MCP client\n\nEvery client runs the same command — `uvx spotify-mcp-jamiew` — with your three Spotify env vars. No clone, no local path.\n\n**Standard config** (works in most clients):\n\n```json\n{\n  \"mcpServers\": {\n    \"spotify\": {\n      \"command\": \"uvx\",\n      \"args\": [\"spotify-mcp-jamiew\"],\n      \"env\": {\n        \"SPOTIFY_CLIENT_ID\": \"your_client_id\",\n        \"SPOTIFY_CLIENT_SECRET\": \"your_client_secret\",\n        \"SPOTIFY_REDIRECT_URI\": \"http://127.0.0.1:8888\"\n      }\n    }\n  }\n}\n```\n\n<details>\n<summary>Claude Code</summary>\n\n```bash\nclaude mcp add spotify \\\n  -e SPOTIFY_CLIENT_ID=your_client_id \\\n  -e SPOTIFY_CLIENT_SECRET=your_client_secret \\\n  -e SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888 \\\n  -- uvx spotify-mcp-jamiew\n```\n\nAdd `-s user` to install it globally across all projects. Verify with `claude mcp list`.\n</details>\n\n<details>\n<summary>Claude Desktop</summary>\n\nAdd the **standard config** above to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows), then fully restart Claude Desktop.\n</details>\n\n<details>\n<summary>Codex CLI</summary>\n\n```bash\ncodex mcp add spotify \\\n  --env SPOTIFY_CLIENT_ID=your_client_id \\\n  --env SPOTIFY_CLIENT_SECRET=your_client_secret \\\n  --env SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888 \\\n  -- uvx spotify-mcp-jamiew\n```\n\nOr add to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.spotify]\ncommand = \"uvx\"\nargs = [\"spotify-mcp-jamiew\"]\n\n[mcp_servers.spotify.env]\nSPOTIFY_CLIENT_ID = \"your_client_id\"\nSPOTIFY_CLIENT_SECRET = \"your_client_secret\"\nSPOTIFY_REDIRECT_URI = \"http://127.0.0.1:8888\"\n```\n</details>\n\n<details>\n<summary>Hermes</summary>\n\nAdd to `~/.hermes/config.yaml`, then run `/reload-mcp` (or restart Hermes):\n\n```yaml\nmcp_servers:\n  spotify:\n    command: uvx\n    args: [spotify-mcp-jamiew]\n    env:\n      SPOTIFY_CLIENT_ID: your_client_id\n      SPOTIFY_CLIENT_SECRET: your_client_secret\n      SPOTIFY_REDIRECT_URI: http://127.0.0.1:8888\n```\n</details>\n\n<details>\n<summary>OpenClaw</summary>\n\nAdd the **standard config** above to `~/.openclaw/openclaw.json` (under `mcpServers`), then `openclaw gateway restart`.\n</details>\n\n<details>\n<summary>Other clients (mcp.json)</summary>\n\nMost MCP clients read a JSON file with an `mcpServers` block — drop the **standard config** above into it.\n\nUsing something else? Paste this to your agent:\n\n> Install the spotify-mcp MCP server from https://github.com/jamiew/spotify-mcp — it's on PyPI as `spotify-mcp-jamiew`, run it with `uvx spotify-mcp-jamiew`, and set env vars `SPOTIFY_CLIENT_ID`, `SPOTIFY_CLIENT_SECRET`, and `SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888`.\n</details>\n\n<details>\n<summary>Run from source (local dev)</summary>\n\n```bash\ngit clone https://github.com/jamiew/spotify-mcp.git\ncd spotify-mcp\nuv sync\n```\n\nThen point your client at the checkout:\n\n```json\n{\n  \"mcpServers\": {\n    \"spotify\": {\n      \"command\": \"uv\",\n      \"args\": [\"--directory\", \"/path/to/spotify-mcp\", \"run\", \"spotify-mcp\"],\n      \"env\": {\n        \"SPOTIFY_CLIENT_ID\": \"your_client_id\",\n        \"SPOTIFY_CLIENT_SECRET\": \"your_client_secret\",\n        \"SPOTIFY_REDIRECT_URI\": \"http://127.0.0.1:8888\"\n      }\n    }\n  }\n}\n```\n\nTo run the latest unpublished commit without cloning: `uvx --from git+https://github.com/jamiew/spotify-mcp.git spotify-mcp`.\n</details>\n\nOn first use the server opens a browser for Spotify OAuth; the token is cached locally for later runs.\n\n## Usage Examples\n\n- **\"Create a chill study playlist with 20 tracks\"** → Search + playlist creation + bulk track addition\n- **\"Show me the first 50 tracks from my 'Liked Songs'\"** → Pagination for large playlists  \n- **\"Find similar artists to Radiohead and add their top tracks to my queue\"** → Search + artist info + queue management\n\n## Development\n\nBuilt with the **FastMCP framework** — focused single-purpose tools spanning playback, search, queue, and playlist management, with type-safe APIs and comprehensive test coverage.\n\n**Debug with MCP Inspector:**\n```bash\nnpx @modelcontextprotocol/inspector uv --directory /path/to/spotify_mcp run spotify-mcp\n```\n",
  "bytes": 8096,
  "sha": "7fb31fac0b1c56090c554323872a80fb72475753fc7be27892fc6ba4e05b5d37",
  "repo_slug": "jamiew/spotify-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_jamiew_spotify_mcp_324027bd/readme"
}