spotify-mcp
Provides tools for searching Spotify and reading playlists, saved tracks, artist catalogs, recommendations, and recently played tracks, as well as creating playlists and adding tracks to them.
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 recommend songs similar to 'Blinding Lights'"
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
An MCP server that wraps spotipy so Claude (or any MCP client) can search Spotify and read playlists, saved tracks, artist catalogs, and discovery signals.
Built specifically as re-com's Spotify backend — read-heavy by design, not a playback-control server. It does support creating playlists and adding tracks to them (so a re-com recommendation list can become a real playlist), but there's no play/pause/queue control; look at one of the several playback-focused Spotify MCP servers already out there for that.
Tools
Tool | Description |
| Search Spotify. |
| List the current user's playlists. Omit |
| Get the tracks in a playlist. Local files/episodes are skipped. |
| Get the user's saved ("Liked Songs") tracks. |
| Get a single track's metadata. |
| Spotify's algorithmic recommendations from one seed track — the closest analog to YouTube Music's radio. |
| Get an artist's profile. |
| An artist's top tracks (Spotify caps this at ~10 — there's no full-catalog endpoint). |
| Artists related to the given one. |
| The user's recently played tracks. |
| Create a new playlist owned by the current user. |
| Add tracks (by ID or URI) to a playlist, chunked in batches of 100. |
| Delete the cached OAuth token. |
A real limitation, stated plainly: Spotify restricts /recommendations and artist_related_artists for API apps created after November 2024 that don't have "Extended Quota Mode" (a manual approval Spotify grants sparingly). If your app doesn't have it, get_recommendations and get_related_artists will 403 — handle_errors turns that into a clear message rather than a raw traceback, and re-com's spotify_client.py treats it as one signal being unavailable, not a fatal error. search_music, playlists, saved tracks, and artist top tracks are unaffected.
Other Claude Code projects on this machine (e.g. re-com) call these tools by spawning this server over MCP rather than talking to spotipy/Spotify themselves — this is the only place Spotify credentials live.
Related MCP server: spotify-mcp
Setup
1. Register a Spotify app
Go to the Spotify Developer Dashboard, create an app.
Add a redirect URI matching
SPOTIFY_REDIRECT_URI(defaulthttp://127.0.0.1:8888/callback— you don't need anything actually listening on that port; see step 3).Note the app's Client ID and Client Secret.
2. Install dependencies
python3 -m venv .venv
source .venv/bin/activate
pip install -e .3. Authenticate
export SPOTIFY_CLIENT_ID="..."
export SPOTIFY_CLIENT_SECRET="..."
python scripts/setup_auth_spotify.pyThis prints an authorization URL, waits for you to log in and paste back the URL you're redirected to (works fine over SSH/headless — nothing needs to bind the redirect port), and writes the resulting token to .spotify_cache (path configurable via SPOTIFY_CACHE_PATH).
.spotify_cache is equivalent to your logged-in session — never commit it or share it. It's already gitignored. Tokens refresh automatically once cached; re-run this script only if refresh itself starts failing (e.g. the app's client secret was rotated, or you revoked access from your Spotify account settings), or if SCOPE in server.py gains new permissions (delete .spotify_cache first so the auth flow re-prompts for consent — a stale cached token won't pick up new scopes on its own).
4. Add to Claude Code
claude mcp add spotify -s user \
-e SPOTIFY_CLIENT_ID="..." \
-e SPOTIFY_CLIENT_SECRET="..." \
-e SPOTIFY_CACHE_PATH="$(pwd)/.spotify_cache" \
-- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"-s user makes it available in any Claude Code session, not just this directory. Use absolute paths for the python interpreter, server.py, and SPOTIFY_CACHE_PATH since the server can be launched from any working directory.
For other MCP clients (Claude Desktop, etc.), point them at the same command and env vars using their respective config format.
Testing
The unit test suite (tests/) runs against a hand-rolled fake spotipy.Spotify client — no network access or Spotify credentials needed:
pip install -e ".[dev]"
pytestError handling
Tool calls translate common failure modes into clear messages instead of raw tracebacks:
Missing/expired auth (401) → tells you to redo authenticate step.
Restricted/forbidden (403) → tells you it's likely a Spotify API access restriction (see the recommendations/related-artists caveat above) or a missing OAuth scope.
Rate limiting (429) → tells you to wait, including the
Retry-Afterhint if Spotify sent one.Any other API or OAuth error is reported directly rather than as a raw traceback.
License
MIT — see LICENSE.
Available Tools
16 toolsadd_tracks_to_playlistA
Add tracks to a playlist by Spotify track ID (or URI). Chunks in batches of 100, Spotify's per-request limit.
Inputs: track_ids (required), playlist_id (required). Returns: result
create_playlistB
Create a new playlist owned by the current user and return it (id, name, ...).
Inputs: name (required), public, description. Returns: object
get_album_tracksA
Get an album's tracks. Omit limit to fetch all of them.
Album track objects are the "simplified" shape and carry no album key of
their own, so callers that need one should attach it from the album they
asked for.
Inputs: album_id (required), limit. Returns: result
get_artistB
Get an artist's profile (name, genres, popularity, images).
Inputs: artist_id (required). Returns: object
get_artist_albumsA
Get an artist's albums and singles. Omit limit to fetch all of them.
This plus get_album_tracks is the only route to an artist's real catalog
that survives Spotify's post-Nov-2024 restrictions: get_artist_top_tracks
403s for apps without Extended Quota Mode and caps at ~10 even when it
works. Appears-on and compilation albums are excluded -- they would credit
the artist for other people's records.
Inputs: artist_id (required), limit. Returns: result
get_artist_top_tracksB
Get an artist's top tracks (Spotify caps this at ~10 -- there's no "full catalog" endpoint the way YouTube Music's channel Songs tab has).
Inputs: artist_id (required). Returns: result
get_current_userA
Get the authenticated user's own profile (id, display_name, ...).
The id is the only way to tell a playlist the user owns from one they
merely follow: get_playlists returns both, indistinguishable except by
owner.id. That distinction is load-bearing rather than cosmetic --
Spotify 403s playlist_items on another user's playlist, so a caller that
treats followed playlists as its own gets an error it cannot act on.
Inputs: no named parameters. Returns: object
get_playlistsA
List the current user's playlists. Omit limit to fetch all of them.
Inputs: limit. Returns: result
get_playlist_tracksA
Get the tracks in a playlist. Omit limit to fetch the entire playlist.
Local files and episodes (no track id) are skipped. See _track_of for
the two payload shapes this has to read.
Inputs: playlist_id (required), limit. Returns: result
get_recently_playedB
Get the user's recently played tracks (each item wraps a "track" key).
Inputs: limit. Returns: result
get_recommendationsA
Get Spotify's algorithmic recommendations seeded from one track.
May 403 if this app doesn't have access to /recommendations -- Spotify restricts it for apps created after Nov 2024 without Extended Quota Mode.
Inputs: seed_track_id (required), limit. Returns: result
get_saved_tracksA
Get the current user's saved ("Liked Songs") tracks. Omit limit for all of them.
Inputs: limit. Returns: result
get_trackB
Get a single track's metadata (title, artists, album, ...).
Inputs: track_id (required). Returns: object
logoutA
Delete the cached Spotify OAuth token.
Subsequent tool calls will fail until you re-authenticate via scripts/setup_auth_spotify.py.
Inputs: no named parameters. Returns: result
search_musicC
Search Spotify. filter is "track" or "artist".
Inputs: query (required), limit, filter. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Most tools are clearly distinct by resource (tracks, playlists, artists, albums, user). Minor overlap: get_playlist_tracks vs get_saved_tracks vs get_recently_played all return track lists, but their source contexts are clear. get_artist_top_tracks and get_artist_albums both provide artist catalog access, though descriptions clarify the distinction.
The set predominantly follows a verb_noun pattern (get_*, create_playlist, add_tracks_to_playlist, search_music, logout). The two exceptions are search_music and logout, which are still readable and not jarring. Overall consistent and predictable.
16 tools is slightly above the ideal 3-15 range but appropriate for Spotify's broad domain (search, user library, playlists, artists, albums, recommendations). Each tool covers a distinct need; no obvious redundancy.
The surface covers search, playlist CRUD (create, read, add tracks), saved tracks, artist/album browsing, and user info. Notable gaps: no update/delete playlist, no remove tracks from playlist, no play/control playback, no track/album search filtering beyond track/artist, and no user's top items. Core browsing is solid but lifecycle coverage is incomplete.
Maintenance
Related MCP Connectors
An MCP server that provides tools to discover and retrieve podcast episodes transcripts.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Reddit MCP server: search posts, subreddit feeds, comments & user profiles as JSON. No API key.
Related MCP Servers
- AlicenseBqualityDmaintenanceAn MCP server that enables users to control Spotify playback, search music, and manage playlists through natural conversation. It is updated for the February 2026 Spotify Web API changes and supports full playlist CRUD operations.68MIT
- AlicenseNot gradedqualityFmaintenanceAn MCP server that enables users to control Spotify playback, search for music, and manage playlists through MCP-compatible clients. It supports features like track recommendations and playback management using secure OAuth authentication.MIT
- AlicenseNot gradedqualityDmaintenanceAn unofficial MCP server that provides access to Spotify's Web API through the Model Context Protocol, enabling AI assistants to search music, manage playlists, and control playback.29 npm9ISC
- FlicenseNot gradedqualityDmaintenanceA MCP server for controlling Spotify playback, searching for content, and managing playlists via OAuth authentication.1-