spotify-mcp
This MCP server lets you build and edit Spotify playlists from natural-language descriptions, using the model as the music recommender.
Search Spotify for tracks and resolve them to URIs (
search_tracks), with query filters like artist, year, genre, and album.Read the user's actual listening history — top tracks or artists over various time ranges (
get_my_taste).List the user's playlists (
list_my_playlists) and view a playlist's full contents with track URIs and positions (get_playlist).Create new playlists, optionally private and with a description (
create_playlist).Add tracks to a playlist, appending or inserting at a position, with automatic batching past Spotify's 100-track limit (
add_tracks).Remove tracks from a playlist, removing every occurrence, with automatic batching (
remove_tracks).Auth and token refresh are handled for you after a one-time login flow.
Allows building and editing Spotify playlists from natural language descriptions, including searching tracks, understanding the user's listening taste, listing and reading playlists, and creating, adding to, or removing tracks from playlists.
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 Make a playlist of upbeat indie rock for running."
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.
An MCP server that lets MCP clients build and edit Spotify playlists from a description. "Moody 90s trip-hop for a rainy commute", "add three more like the last one", "drop anything over five minutes", etc. This is just a personal project intended for personal use, if you find it useful, that's a side effect, and you're welcome to use it.
How it works
Spotify deprecated /recommendations, /audio-features, /audio-analysis and related-artists
for every app created after 2024-11-27, they return 403 and have no replacement. So the model
itself is the recommendation engine. These seven tools give it the three things it can't do itself:
Tool | Purpose | |
Resolve |
| Turn "Massive Attack – Teardrop" into a track URI. Supports |
Ground |
| Your real top tracks/artists, so "music like I listen to" means something |
Read |
| Find a playlist by name; see what's in it before editing |
Write |
| Build and edit. Batched past Spotify's 100-track-per-request cap automatically |
There's a similar project named spotify-mcp-server by Marcel Marais that exposes many more functionalities. If you want to use this tool but find that the current list of exposed functions aren't enough for what you want to do, I'd recommend looking at his MCP server instead.
Related MCP server: playlist-agent
Setup
1. Create a Spotify app
At developer.spotify.com/dashboard → Create app.
Footgun 1 — the redirect URI. Spotify rejects
localhost. Register the IP literal, exactly:http://127.0.0.1:8888/callback
Footgun 2 — the allowlist. New apps are in development mode: capped at 5 users, and each one must be added under Settings → User Management by their Spotify account email — including your own. Miss this and every API call 403s despite a perfectly valid token. (Extended quota has been organizations-only since 2025-05-15 and requires 250k+ monthly actives, so 5 users is the practical ceiling.)
Copy the Client ID and Client secret.
2. Build and log in
npm install && npm run build
export SPOTIFY_CLIENT_ID=...
export SPOTIFY_CLIENT_SECRET=...
npm run loginnpm run login prints an authorization URL (and tries to open your browser), catches the callback
on 127.0.0.1:8888, and writes a refresh token to ~/.config/spotify-mcp/token.json with mode
0600. One time only — the server refreshes access tokens itself from then on.
Scopes requested: playlist-modify-public, playlist-modify-private, playlist-read-private,
playlist-read-collaborative, user-top-read. No playback scopes — this server doesn't control
playback.
3. Register with your MCP client
claude mcp add spotify \
--env SPOTIFY_CLIENT_ID=... \
--env SPOTIFY_CLIENT_SECRET=... \
-- node /absolute/path/to/spotify-mcp/dist/index.jsOr in a client config file:
{
"mcpServers": {
"spotify": {
"command": "node",
"args": ["/absolute/path/to/spotify-mcp/dist/index.js"],
"env": {
"SPOTIFY_CLIENT_ID": "...",
"SPOTIFY_CLIENT_SECRET": "..."
}
}
}
}Then just ask: "Make me a 20-track playlist of moody 90s trip-hop for a rainy commute."
Development
npm test # node:test, no framework — chunking, pagination, token refresh, error handling
npm run build
npx @modelcontextprotocol/inspector node dist/index.js # poke the tools by handSet SPOTIFY_MCP_TOKEN_FILE to override the token location.
Stack: @modelcontextprotocol/server v2 + zod. Everything else is a Node built-in — no express,
no axios, no dotenv, no Spotify client library.
Notes
Auth flow: authorization code with client secret, not PKCE. Spotify doesn't rotate refresh tokens on this flow, so there's no lose-the-write-lose-the-account failure mode. Everything stays on loopback.
The playlist endpoints moved. Separately from the 2024-11-27 cull, Spotify retired the
/tracksplaylist surface in favour of/items. Unlike the cull these do have replacements, and the server uses them. Everything below 403s on the left, works on the right:GET/POST/DELETE /playlists/{id}/tracks→.../items;POST /users/{id}/playlists→POST /me/playlists;item.trackon a playlist entry →item.item;playlist.tracks.totalin/me/playlists→playlist.items.total; and the DELETE body key{"tracks": [...]}→{"items": [...]}. That last one isn't in Spotify's changelog — it 403s as "Insufficient client scope", which sends you hunting for a scope problem you don't have./me/playlistslies about being empty. It returns a valid, empty page roughly 40% of the time on an account that demonstrably has playlists. An empty list is a silently wrong answer rather than an error, solist_my_playlistsretries up to four times before believing it. Itsitems.totalcount also lags behind writes by a few seconds; the playlist itself is correct.Playlist visibility is not settable.
publicis accepted at creation and on update, returns 200, and is then ignored — new playlists come back public regardless. Flip it in the Spotify client. Nothing to fix here; the API just doesn't honour the field.Not included: playback control, playlist rename/reorder, saved-library reads. Add when wanted.
Available Tools
7 toolsadd_tracksAdd tracks to a playlistA
Append tracks to a playlist (or insert at a position). Pass as many URIs as you like — they are batched automatically. Get URIs from search_tracks; do not invent them.
Inputs: uris (required), playlist_id (required), position.
create_playlistCreate a playlistA
Create a new empty playlist, then fill it with add_tracks. Give it a name and a short description that reflects what the user asked for. Returns the playlist ID and its URL.
Inputs: name (required), public, description.
get_my_tasteGet my top tracks or artistsA
The user's actual listening history — the best available signal for what they like. Read this before building a playlist described in terms of the user's own taste ("music like what I listen to", "more of this vibe"), then choose similar music yourself. Spotify's recommendation and audio-feature endpoints no longer exist for this app. Pick the music yourself from your own knowledge, then use search_tracks to resolve each pick to a URI. Use get_my_taste to ground picks in what this user actually listens to.
Inputs: type, limit, time_range.
get_playlistGet playlist contentsA
Full track listing of a playlist, with each track's URI and its 0-based position. Read this before editing so you know what is already there — it prevents duplicate adds and lets you remove exactly the right tracks.
Inputs: playlist_id (required).
list_my_playlistsList my playlistsA
The user's playlists, with IDs. Use this to find an existing playlist to edit when the user names one ("add these to my Focus playlist") instead of creating a new one.
Inputs: no named parameters.
remove_tracksRemove tracks from a playlistA
Remove every occurrence of the given tracks from a playlist. Batched automatically. Call get_playlist first to confirm the exact URIs present.
Inputs: uris (required), playlist_id (required).
search_tracksSearch tracksA
Find tracks on Spotify and get their URIs. This is how you turn an artist/title you have in mind into something you can add to a playlist. Supports Spotify query syntax: artist:Portishead, year:1990-1999, genre:trip-hop, album:Dummy, and quoted phrases. Search one track at a time for precision. Spotify's recommendation and audio-feature endpoints no longer exist for this app. Pick the music yourself from your own knowledge, then use search_tracks to resolve each pick to a URI. Use get_my_taste to ground picks in what this user actually listens to.
Inputs: query (required), limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a clearly distinct action: searching tracks, reading listening history, listing playlists, reading a playlist's contents, creating playlists, adding tracks, and removing tracks. The descriptions further reinforce boundaries, so an agent should not confuse them.
All tool names follow a consistent verb_noun snake_case pattern: search_tracks, get_my_taste, list_my_playlists, get_playlist, create_playlist, add_tracks, remove_tracks. There are no mixed conventions or vague verbs.
Seven tools is well-scoped for a Spotify playlist-management server. Each tool covers a necessary step in the core workflow without redundancy or bloat.
The playlist workflow is well covered: discover via search/taste, list/read playlists, create playlists, and add/remove tracks. Minor gaps like renaming or deleting playlists are missing, but they are not central to the apparent purpose.
Related MCP Connectors
Create, inspect, and manage Wubble music, speech, voice, and sound-effect requests through MCP.
Spotify MCP server for ChatGPT, Claude and any AI agent: search songs and artists, list playlists, read playlist songs, create playlist, add songs to playlist, remove songs from playlist, set playlist public or private and save to Liked Songs in your own Spotify account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Spotify yourself; Cotlet does not store your password and you need no Spotify API key. About the official Spotify API: Spotify has a full Web API and, since 23 Apr 2026, an official connector for Claude (checked 5 Nov 2026). The API needs an app you register, and in development mode the app owner must have Premium and the app allows 5 users; unlimited users need a registered business with at least 250,000 monthly users. Setup and FAQ: https://cotlet.dev/integrations/spotify-api-mcp-server
Spotify MCP — Web API via client_credentials OAuth
Manage Superlist tasks and lists in plain language from any MCP-compatible AI agent.
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
- FlicenseBqualityDmaintenanceEnables natural-language creation, management, and optimization of Spotify playlists via MCP tools like search, generate, analyze, and recommend.12-
- FlicenseNot gradedqualityCmaintenanceEnables searching Spotify and managing playlists from any MCP client using natural language.-
- AlicenseNot gradedqualityBmaintenanceEnables MCP-compatible AI assistants to control Spotify Premium accounts by searching music, managing playback and devices, handling queues, creating and editing playlists, and browsing or modifying the library.MIT