spotify-mcp
Provides tools for interacting with Spotify, including playback control, queue management, searching and resolving tracks/artists, retrieving audio features and recommendations, managing playlists in bulk, and managing saved tracks/albums and followed artists.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@spotify-mcp play Bohemian Rhapsody on my active device"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
spotify-mcp
A dependency-free Model Context Protocol server for Spotify. It speaks stdio JSON-RPC 2.0, uses only the Python standard library, and gives an MCP client (Claude Code, Claude Desktop, anything that speaks MCP) 36 tools for playback, queue, search, library and bulk playlist management. A small CLI is included.
Built by Robert Lingoes with AI coding agents (Claude Code / Codex); Robert owns the architecture, requirements and review.
Features
Zero dependencies. Python 3.9+ and nothing to
pip installto run it.Bulk playlist work. Add any number of tracks by name or URI; names are auto-resolved, de-duplicated against the playlist, and chunked to Spotify's 100-per-call limit (10,000-track playlist ceiling is enforced up front).
Safe by default. Destructive tools (remove, empty, delete, unsave, unfollow) return a dry-run preview unless you pass
confirm=true.Robust auth. Access tokens are minted from your refresh token, cached with
0600permissions, refreshed under a cross-process lock, and retried once on401.429responses honorRetry-After.Flexible inputs. Anywhere an id is expected you can pass a raw id, a
spotify:URI, or anopen.spotify.comURL.
Related MCP server: Apple Music
Tools
Group | Tools |
Playback |
|
Search and discovery |
|
Playlists |
|
Library and follows |
|
Playback tools need Spotify Premium and an active device.
Setup
1. Create a Spotify developer app
Go to the Spotify developer dashboard and create an app.
Under the app's settings add this Redirect URI (exact match):
http://127.0.0.1:8888/callbackCopy the app's Client ID and Client Secret.
2. Get a refresh token
export SPOTIFY_CLIENT_ID="your-client-id"
export SPOTIFY_CLIENT_SECRET="your-client-secret"
python3 auth_setup.py # use --no-browser to just print the URLauth_setup.py runs the standard authorization-code flow (with PKCE) against a temporary server on 127.0.0.1:8888, then prints a refresh token once. It stores nothing on disk. Use a different port by setting SPOTIFY_REDIRECT_URI (and registering it in the dashboard); it must be a loopback address.
Scopes requested:
user-read-playback-state user-modify-playback-state
user-read-currently-playing user-read-recently-played
user-read-playback-position user-top-read
playlist-read-private playlist-read-collaborative
playlist-modify-public playlist-modify-private
user-library-read user-library-modify
user-follow-read user-follow-modify3. Configure credentials
The server reads three environment variables:
Variable | Meaning |
| your app's client id |
| your app's client secret |
| the token printed by |
Optional:
Variable | Default | Meaning |
|
| where the token cache ( |
|
| set to |
Spotify may rotate the refresh token on refresh; the cache keeps the newest one. If you paste a new SPOTIFY_REFRESH_TOKEN into your config, the stale cache is ignored automatically.
Never commit these values. Keep them in your MCP client config or a secrets manager.
Use with Claude Code
claude mcp add spotify \
--env SPOTIFY_CLIENT_ID=your-client-id \
--env SPOTIFY_CLIENT_SECRET=your-client-secret \
--env SPOTIFY_REFRESH_TOKEN=your-refresh-token \
-- python3 -m spotify_mcpRun it from a checkout of this repo (so python3 -m spotify_mcp resolves), or pip install . first, which installs a spotify-mcp command; then the last line is simply -- spotify-mcp.
Equivalent .mcp.json:
{
"mcpServers": {
"spotify": {
"command": "python3",
"args": ["-m", "spotify_mcp"],
"cwd": "/path/to/spotify-mcp",
"env": {
"SPOTIFY_CLIENT_ID": "your-client-id",
"SPOTIFY_CLIENT_SECRET": "your-client-secret",
"SPOTIFY_REFRESH_TOKEN": "your-refresh-token"
}
}
}
}Use with Claude Desktop
Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) and restart the app:
{
"mcpServers": {
"spotify": {
"command": "python3",
"args": ["-m", "spotify_mcp"],
"cwd": "/path/to/spotify-mcp",
"env": {
"SPOTIFY_CLIENT_ID": "your-client-id",
"SPOTIFY_CLIENT_SECRET": "your-client-secret",
"SPOTIFY_REFRESH_TOKEN": "your-refresh-token"
}
}
}
}After pip install . you can replace command/args/cwd with "command": "spotify-mcp".
CLI
The same operations are available from the shell (python3 -m spotify_mcp.cli ..., or spotify-mcp-cli once installed):
spotify-mcp-cli now
spotify-mcp-cli search "daft punk" --limit 5
spotify-mcp-cli create "Road Trip" --desc "windows down"
spotify-mcp-cli add <playlist_id> "Blinding Lights" "Mr Brightside by The Killers"
spotify-mcp-cli add <playlist_id> --file songs.txt # one song per line
cat songs.txt | spotify-mcp-cli add <playlist_id> --stdin
spotify-mcp-cli remove <playlist_id> "some song" --confirmDevelopment Mode caveats
Spotify limits apps in "Development Mode", and its Web API has been changing. Depending on your app's tier, some endpoints may return 403 (for example certain playlist-write, library-save or follow calls), and recommendations / audio_features have been restricted for newer apps; those two tools return an explanatory error instead of failing hard. A 403 is passed through unchanged so you can see exactly what Spotify said. This project does not work around Spotify's access policies.
Tests
No network, no credentials: all HTTP is mocked.
python3 -m pytest # or: python3 -m unittest discover -s tests -vLicense
MIT. See LICENSE.
Available Tools
36 toolsartist_catalogC
An artist's top tracks or album catalog (name/URI/URL accepted).
Inputs: artist (required), kind, limit.
audio_featuresB
Audio features (tempo/energy/danceability) for a track (Spotify has restricted this endpoint for newer apps; may return an explanatory error).
Inputs: track (required).
devicesA
List available playback devices (speakers, desktop apps, phone).
Inputs: no named parameters.
follow_artistsB
Follow artists (needs follow scope).
Inputs: items (required).
followed_artistsC
Artists you follow (needs follow scope — needs the user-follow-* scopes).
Inputs: limit.
now_playingA
What's currently playing on Spotify (track, artist, album, progress).
Inputs: no named parameters.
pauseB
Pause playback.
Inputs: no named parameters.
playB
Resume playback, or play a specific track/album/playlist URI.
Inputs: uri.
playlist_addB
Bulk-add songs (names or URIs) to a playlist. Auto-resolves names, dedupes, and chunks any number of songs up to Spotify's 10k/playlist ceiling.
Inputs: items (required), playlist_id (required), dedupe.
playlist_createC
Create a new playlist.
Inputs: name (required), public, description.
playlist_deleteA
Delete (unfollow) a playlist. DESTRUCTIVE — needs confirm=true.
Inputs: playlist_id (required), confirm.
playlist_emptyA
Remove ALL tracks from a playlist. DESTRUCTIVE — needs confirm=true.
Inputs: playlist_id (required), confirm.
playlist_getC
Get a playlist's details + tracks (paginated).
Inputs: playlist_id (required), limit, offset.
playlist_listC
List your playlists (with ids + track counts).
Inputs: limit.
playlist_removeA
Remove songs from a playlist. DESTRUCTIVE — needs confirm=true, else returns a dry-run preview.
Inputs: items (required), playlist_id (required), confirm.
playlist_renameC
Rename a playlist.
Inputs: name (required), playlist_id (required).
playlist_reorderC
Move a track (or range) to a new position in a playlist.
Inputs: playlist_id (required), range_start (required), insert_before (required), range_length.
playlist_set_detailsC
Update a playlist's name / description / public flag.
Inputs: playlist_id (required), name, public, description.
previousB
Go to the previous track.
Inputs: no named parameters.
queueC
Add a track URI to the playback queue.
Inputs: uri (required).
recent_tracksC
Recently played tracks.
Inputs: limit.
recommendationsB
Recommendations from seed tracks/artists/genres (Spotify has restricted this endpoint for newer apps; may return an explanatory error).
Inputs: limit, seed_genres, seed_tracks, seed_artists.
resolveB
Resolve a track name (e.g. 'Blinding Lights by The Weeknd') to its URI.
Inputs: text (required).
save_albumsC
Save albums (ids/URIs/URLs).
Inputs: items (required).
saved_albumsC
Your saved albums.
Inputs: limit.
saved_tracksD
Your Liked Songs.
Inputs: limit.
save_tracksB
Add songs (names or URIs) to Liked Songs.
Inputs: items (required).
searchC
Search tracks/artists/albums/playlists. Optional year & genre filters.
Inputs: query (required), year, genre, limit, +1 more.
seekB
Seek to a position (milliseconds) in the current track.
Inputs: ms (required).
skipA
Skip to the next track.
Inputs: no named parameters.
top_tracksC
Your top tracks over short/medium/long term.
Inputs: limit, time_range.
transferC
Move playback to a specific device by id.
Inputs: device_id (required).
unfollow_artistsA
Unfollow artists. DESTRUCTIVE — needs confirm=true (needs follow scope).
Inputs: items (required), confirm.
unsave_albumsB
Remove saved albums. DESTRUCTIVE — needs confirm=true.
Inputs: items (required), confirm.
unsave_tracksA
Remove songs from Liked Songs. DESTRUCTIVE — needs confirm=true.
Inputs: items (required), confirm.
volumeB
Set playback volume 0-100.
Inputs: pct (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 36 tools
Most tools target a clearly distinct resource or action, and the playback/library/playlist clusters are cleanly separated. The main overlap is playlist_rename versus playlist_set_details (both can change a playlist's name), and resolve versus search have related but distinguishable purposes.
Naming mixes conventions: single verbs (play, pause, skip), noun-first (saved_tracks, now_playing, top_tracks), verb_noun (save_albums, follow_artists), and noun_verb for the playlist_* family. The playlist_ prefix is internally consistent and everything stays readable, but there is no single predictable pattern across the server.
36 tools is on the heavy side, but the domain (playback control, library, discovery, and full playlist CRUD) genuinely warrants many operations. It sits at the borderline where a few tools (e.g. separate rename and set_details) could be consolidated.
Coverage is broad and coherent: playback, library management, search/discovery, and playlist lifecycle all have create/read/update/delete paths with sensible destructive guards. Minor gaps remain, e.g. shuffle/repeat mode toggles and dedicated album/artist detail retrieval.
Maintenance
Related MCP Connectors
Spotify MCP — Web API via client_credentials OAuth
Create, inspect, and manage Wubble music, speech, voice, and sound-effect requests through MCP.
Discover MCP servers and A2A agents; verify, message, post, follow, react, and receive webhooks.
Inspect and edit media canvases, run existing Flows, and retrieve results. Vyrl MCP token required.
Related MCP Servers
- FlicenseNot gradedqualityAmaintenanceEnables MCP clients to search and manage playlists, library, catalog, discovery, playback, and the Up Next queue across macOS, Windows, and Linux.-
- FlicenseNot gradedqualityAmaintenanceEnables MCP clients to control playlists, library, catalog, discovery, playback, and the Up Next queue across macOS, Windows, and Linux.-
- FlicenseNot gradedqualityAmaintenanceEnables MCP clients to search and manage playlists, library, catalog, discovery, playback, and the Up Next queue, picking per call among native Music.app, browser web-player, and web API engines on macOS, Windows, and Linux. Only a Mac or an Apple Music subscription is required.-
- FlicenseNot gradedqualityAmaintenanceEnables MCP clients to manage Apple Music playlists, library, catalog, discovery, playback, and the Up Next queue across macOS, Windows, and Linux using native Music.app, the Apple Music API, Safari, or Chrome engines.-