spotify-mcp
This server lets Claude manage your Spotify playlists, inspect your Spotify account and listening activity, analyze your local listening history from a Spotify data export, and resolve song candidates into verified playlists.
Account & library reads: view your profile, current playback state, top artists/tracks, recently played, saved tracks/albums, followed artists, and your playlists (including playlist contents, with the caveat that non-owned playlists return 403).
Catalog lookups: search the Spotify catalog and fetch detailed metadata for tracks, artists, albums, artist albums, and album tracklists.
Playlist writing with confirmation: create playlists, add/replace/reorder items, update details, set cover images, and remove items — every write is two-phase (preview + confirm token), supports dry-run mode, and is logged to an audit file.
Local listening-history analytics (from your Spotify export, not the API): overall summaries, hour/day-of-week patterns, skip-rate leaderboards, top artists/tracks/albums, taste drift between two periods, dropped artists, tracks to rediscover, plus a guarded read-only SQL tool for custom questions.
Track resolution & playlist building: turn {artist, title} pairs into verified Spotify track URIs (with strict artist matching), and build a finished playlist from a candidate list in one confirmed flow.
Server introspection: check authorization status, granted scopes, dry-run mode, removal toggle, analytics DB state, and HTTP cache stats.
Provides tools for managing Spotify playlists and account data, including reading playback state, top artists/tracks, recently played items, saved albums and tracks, playlist creation and editing, resolving tracks into playlists, and analyzing local listening history from Spotify data exports.
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 Create a playlist from my top tracks of the year"
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 personal MCP server that lets Claude manage your Spotify playlists and answer questions about your actual listening history. Built for one user, running on your own machine — see PLAN.md for the full design, including the places where Spotify's 2026 API changes make something outright impossible rather than just harder.
35 tools across four areas:
Reading your account — playback state, top artists/tracks, recently played, saved tracks/albums, followed artists, playlists, catalog search, track/artist/album metadata.
Writing playlists — create, add/replace/reorder items, edit details, set a cover image, remove items — every one previewed before it executes.
Local listening-history analytics — summaries, hour-of-day/day-of-week breakdowns, skip rates, top artists/tracks/albums, taste drift between two periods, artists you've dropped, tracks worth rediscovering, and a guarded free-form SQL tool for anything the named ones don't cover. Built from your Spotify data export, not the API — the API has no analytics endpoints left.
Resolving a list into a playlist — turn
{artist, title}pairs (e.g. from a web search for "today's top songs") into verified Spotify tracks and, optionally, a finished playlist.
Setup
Create a Spotify app. Go to the Spotify Developer Dashboard and create an app — Development Mode is fine, this is a personal project. Note its Client ID; no client secret is used (this server authorizes via PKCE).
Two Spotify-side requirements as of 2026, not something this project controls: the account that owns the app needs Spotify Premium, and each Development Mode app is capped at 5 authorized users. Every person running this server needs to create their own app and use their own Client ID — this repo never bakes one in.
Register the redirect URI. In the app's settings, add exactly:
http://127.0.0.1:8888/callback(If you change
SPOTIFY_REDIRECT_PORTin step 4, update this to match.)Install dependencies (requires uv):
uv syncConfigure. Copy
.env.exampleto.envand paste in your Client ID. The rest of the file is commented — the defaults are sensible for personal use, but at minimum consider settingSPOTIFY_MCP_TIMEZONE(see Local analytics below).cp .env.example .envAuthorize. Opens your browser for a one-time Spotify login and saves a refresh token locally:
uv run spotify-mcp loginWire it into Claude Desktop. Add to
claude_desktop_config.json:{ "mcpServers": { "spotify": { "command": "uv", "args": ["run", "--directory", "/absolute/path/to/spotify-mcp", "spotify-mcp", "serve"] } } }Restart Claude Desktop. You should see all 35 tools available.
To run it standalone instead (e.g. for the smoke tests below):
uv run spotify-mcp serve
A config change to .env only takes effect on the next restart of the
server process — it reads the file once at startup and doesn't watch it.
If you change something and nothing seems different, restart the
connection (quit/reopen Claude Desktop, or reconnect the MCP server).
Related MCP server: Spotify MCP Server
Playlist writes and confirmation
Every write tool (create_playlist, add_playlist_items,
replace_playlist_items, reorder_playlist_items,
update_playlist_details, set_playlist_cover, remove_playlist_items,
build_playlist_from_candidates) is two-phase: call it once and it returns
a preview plus a one-time confirm_token — nothing is sent to Spotify yet.
Call it again with that token and the exact same arguments to actually
execute; changing anything invalidates the token, and a token can only be
used once regardless of whether that attempt succeeds. Claude should always
show you the preview before calling back with the token.
With SPOTIFY_MCP_DRY_RUN=true (the .env.example default), the second
call still runs the full confirmation flow but never reaches Spotify —
you'll get "status": "dry_run" back showing exactly what would have been
sent. Flip it to false once you trust what you're seeing.
remove_playlist_items is disabled by default — it's the one genuinely
destructive tool here. Set SPOTIFY_MCP_ALLOW_REMOVALS=true if you want it
available. replace_playlist_items also discards existing content and
always shows what would be lost in its preview, but isn't gated behind that
flag — rebuilding a playlist wholesale (e.g. refreshing a chart playlist
periodically) is a normal, intentional workflow.
A local audit log of every executed (or dry-run) write is kept at
<user data dir>/spotify-mcp/audit.jsonl — one JSON line per write, with a
timestamp, the action, a hash of its arguments, and the resulting
snapshot_id where relevant.
Local listening-history analytics
Nine tools query a local DuckDB database built from your own data — none of this comes from the Spotify API, which has no analytics endpoints left as of 2026.
Try it now with synthetic data, before your real export arrives:
uv run spotify-mcp make-fixture ./fixture
uv run spotify-mcp ingest ./fixtureThis generates ~8000 realistic plays across 26 months (artists that fade
out, artists that show up recently, a diurnal listening curve, a believable
skip pattern) into <user data dir>/spotify-mcp/listening.duckdb. Ask
Claude "when do I listen the most?" or "which artists have I dropped?" and
it'll answer from this synthetic data — good for seeing the tools work, not
for learning anything about your actual listening.
Request your real data: Spotify → Settings → Account → Privacy
settings → Request data → Extended streaming history. This can take
several weeks to arrive. It downloads as one or more endsong_N.json (or
similarly named) files — ingest reads every .json file in the directory
you point it at, so just extract the download and run:
uv run spotify-mcp ingest /path/to/your/spotify-exportThis replaces whatever was ingested before (fixture or an earlier real
export) — the analytics tables are always fully rebuilt from everything
ever ingested. Re-running ingest on files you've already loaded is a
no-op (tracked by content hash), so it's safe to point it at the same
directory repeatedly, e.g. after Spotify sends you a newer export.
Set your timezone or hour-of-day/day-of-week results mean nothing — without it, everything is bucketed in UTC:
SPOTIFY_MCP_TIMEZONE=Europe/Zagreb(any IANA zone name). Re-run ingest after changing it — local-time
columns are computed at ingest time, not on the fly.
query_listening_history is a guarded free-form SQL tool for anything the
eight named tools don't cover — read docs/analytics_schema.md (or ask
Claude to call describe_listening_data) for the schema. It only accepts a
single read-only SELECT/WITH statement; stacked statements and
file-reading functions are rejected before they ever reach the database.
Resolving tracks and building playlists from a list
resolve_tracks turns {artist, title} pairs into verified Spotify track
URIs. It never accepts a match on title text alone — the artist has to
genuinely match too, which is what stops a search for a popular song from
quietly handing back a karaoke cover, a sped-up edit, a tribute-band
recording, or a live version instead of the real track. Every input ends
up in exactly one of resolved or unresolved; nothing is silently
substituted or dropped.
build_playlist_from_candidates chains that resolution into creating a
playlist: give it a name and a candidate list, and it previews what would
resolve and what wouldn't before creating anything, then follows the same
confirm-token flow as every other write tool.
Neither tool knows what's popular or trending — Spotify removed every
signal that could answer that in 2026. For "make me a playlist of the best
pop songs right now," the chart itself has to come from somewhere else — a
web search, most naturally — and you hand the resulting list to
build_playlist_from_candidates. Claude should be upfront that the
freshness claim rests on whatever it found on the web, not on anything
Spotify itself is asserting.
Resolutions are cached (by normalized artist|title) in
<user data dir>/spotify-mcp/resolver_cache.duckdb, so re-running the same
candidate list — e.g. after fixing a couple of unresolved entries — doesn't
re-search everything from scratch.
Checking what the API actually returns
Spotify's Web API changed substantially in 2026, and the reference docs
still show some fields (popularity, preview_url, ...) marked
"Deprecated" rather than confirming they're gone. Rather than guess, this
repo checks empirically:
uv run python scripts/probe_api.pyThis hits each endpoint once with your authorized account (read-only) and
writes docs/observed_shapes.md — the actual response shapes this app's
Dev Mode tier receives. That file is gitignored (it can contain your own
playlist/listening data); re-run it any time you want current ground truth
instead of relying on this repo's models being right.
Where things live
What | Path |
OAuth token |
|
Listening-history DB |
|
Resolver cache |
|
Write audit log |
|
HTTP ETag cache |
|
Logs | stderr, JSON lines (stdout is reserved for the MCP protocol) |

Never commit the token file, the databases, or .env — all gitignored
already.
Development
uv run pytest
uv run ruff check .
uv run ruff format .All settings in .env.example map 1:1 to fields on Settings in
src/spotify_mcp/config.py — that file is the source of truth if the
example ever drifts.
Available Tools
35 toolsadd_playlist_itemsA
Add tracks/episodes to a playlist by URI. Spotify accepts at most 100 URIs per request; this tool chunks automatically, so 250 tracks = 3 API calls under the hood (all covered by one confirmation). Append-only and does NOT deduplicate — check get_playlist_items first if duplicates matter. position (0-based) only guarantees exact placement for the first 100 URIs; any beyond that append at the end regardless of position. The preview shows the URIs verbatim: resolve them to human-readable names yourself first (e.g. via search_catalog) so you can show the user something readable.
Inputs: uris (required), playlist_id (required), position, confirm_token. Returns: The one return shape every write tool uses — see PLAN.md §2 on why a single con…
build_playlist_from_candidatesA
Resolve {artist, title} candidates and build a new playlist from whatever resolves, in one two-phase call (resolve -> create playlist -> add tracks). Chart freshness comes entirely from wherever the candidate list came from — this tool cannot tell you what's currently popular on Spotify's own authority; say so to the user rather than implying otherwise. The preview always shows both the resolved tracks and the unresolved list before anything is created, and is marked low_confidence if fewer than ~70% of candidates resolved. skip_unresolved=false refuses to create anything unless every single candidate resolves.
Inputs: name (required), candidates (required), public, description, +2 more. Returns: The one return shape every write tool uses — see PLAN.md §2 on why a single con…
create_playlistA
Create a new, empty Spotify playlist. Requires confirmation (call once for a preview, again with confirm_token to execute — see the tool's response for exactly how). collaborative and public cannot both be true.
Inputs: name (required), public, description, collaborative, +1 more. Returns: The one return shape every write tool uses — see PLAN.md §2 on why a single con…
describe_listening_dataARead-only
Describe the local listening-history schema: tables, views, columns, and example queries. Read this before writing SQL for query_listening_history — it also documents what is_skip actually means and its limitations.
Inputs: no named parameters. Returns: schema_markdown
dropped_artistsARead-only
Artists you used to play a lot but have gone quiet on: at least min_plays total plays, with none in the last silent_since_months. Ranked by historical play count.
Inputs: limit, min_plays, silent_since_months. Returns: rows
get_album_tracksCRead-only
An album's tracklist.
Inputs: album_id (required), limit, offset. Returns: href, next, items, limit, +3 more
get_artistARead-only
Full metadata for one artist by its Spotify id.
Inputs: artist_id (required). Returns: GET /artists/{id}. No `followers`, no `popularity`.
get_artist_albumsBRead-only
An artist's albums. include_groups filters by relationship — a comma-separated subset of album,single,appears_on,compilation; omit for all.
Inputs: artist_id (required), limit, offset, include_groups. Returns: href, next, items, limit, +3 more
get_followed_artistsARead-only
Artists the user follows. Cursor-paginated: pass the last returned artist id as after.
Inputs: after, limit. Returns: GET /me/following?type=artist wraps the cursor page under `artists`.
get_meARead-only
Return the current user's Spotify profile: id, display name, uri, images, follower count. Note: email, country, and product tier were removed from this endpoint by Spotify in February 2026 and are never present.
Inputs: no named parameters. Returns: GET /me. No `email`, `country`, `product`, or `explicit_content` — confirmed re…
get_my_playlistsCRead-only
Playlists the user owns or follows.
Inputs: limit, offset. Returns: href, next, items, limit, +3 more
get_playback_stateARead-only
Current Spotify playback state: what's playing, on which device, progress, shuffle/repeat. Returns active=false (nothing else populated) when no device is active — that is normal, not an error.
Inputs: no named parameters. Returns: GET /me/player. `active=False` (nothing else populated) when Spotify returns 20…
get_playlistARead-only
Metadata for one playlist (name, description, owner, item count) — not its contents. Use get_playlist_items for the tracks. Works for any playlist id, but the item count is only meaningful for playlists you own or collaborate on.
Inputs: playlist_id (required). Returns: The lean shape `get_playlist` returns — metadata plus item count, not the items…
get_playlist_itemsARead-only
Tracks (and episodes) in a playlist, paginated. IMPORTANT: only works for playlists the user owns or collaborates on — Spotify returns 403 for any other playlist, including every Spotify-editorial playlist. There is no way around this restriction. Each item's item field holds the track/episode object.
Inputs: playlist_id (required), limit, offset. Returns: href, next, items, limit, +3 more
get_recently_playedARead-only
The user's last-played tracks, most recent first. Spotify caps this at the last 50 plays — it is NOT a full listening history (use the local analytics tools for that, once built). after_ms/before_ms are Unix ms timestamps and mutually exclusive.
Inputs: limit, after_ms, before_ms. Returns: href, next, items, limit, +2 more
get_saved_albumsBRead-only
Albums saved to the user's library, most recently added first.
Inputs: limit, offset. Returns: href, next, items, limit, +3 more
get_saved_tracksARead-only
Tracks saved to the user's library ('Liked Songs'), most recent first.
Inputs: limit, offset. Returns: href, next, items, limit, +3 more
get_top_artistsARead-only
The user's most-played artists over a time window (short_term=~4 weeks, medium_term=~6 months, long_term=~1 year). This is Spotify's own affinity ranking, computed from listening history — not a live popularity/trending signal (Spotify removed those in 2026).
Inputs: limit, offset, time_range. Returns: href, next, items, limit, +3 more
get_top_tracksARead-only
The user's most-played tracks over a time window (short_term=~4 weeks, medium_term=~6 months, long_term=~1 year). Spotify's own affinity ranking from listening history — not a live popularity/trending signal.
Inputs: limit, offset, time_range. Returns: href, next, items, limit, +3 more
get_trackARead-only
Full metadata for one track by its Spotify id.
Inputs: track_id (required). Returns: GET /tracks/{id}. No `popularity`, `available_markets`, `linked_from`, `preview…
listening_by_hourARead-only
Play counts and hours by local hour of day, day of week, or both. by is 'hour', 'dow' (1=Monday..7=Sunday), or 'hour_dow'. Uses whatever timezone was configured at ingest (SPOTIFY_MCP_TIMEZONE) — check server_status or describe_listening_data if results look shifted from your actual clock.
Inputs: by, end, start. Returns: by, buckets
listening_summaryARead-only
Overall listening totals, optionally within a date range (start/end as YYYY-MM-DD). Includes an overall skip rate — see describe_listening_data for what is_skip means and why it's a heuristic, not ground truth.
Inputs: end, start. Returns: latest_play, total_hours, total_plays, earliest_play, +3 more
query_listening_historyARead-only
Run a read-only SQL query (SELECT/WITH only) against the local listening database — the escape hatch for questions the named analytics tools don't cover. Call describe_listening_data first for the schema. Exactly one statement; no INSERT/UPDATE/DELETE/CREATE/ATTACH/PRAGMA/file-reading functions — all rejected before execution. Capped at a few thousand rows (truncated: true if hit) and a several-second timeout.
Inputs: sql (required). Returns: rows, columns, row_count, truncated, +1 more
rediscover_tracksARead-only
Tracks you played a lot during a past window (played_start/played_end, YYYY-MM-DD) but haven't touched in not_since_months — e.g. '40 tracks I played a lot in 2023 but haven't touched since'. Returns track URIs ready to hand to build_playlist_from_candidates or add_playlist_items once you've reviewed them.
Inputs: played_end (required), played_start (required), limit, min_plays, +1 more. Returns: rows
remove_playlist_itemsADestructive
DESTRUCTIVE. Remove specific items from a playlist by URI. Disabled by default — set SPOTIFY_MCP_ALLOW_REMOVALS=true to enable. Requires a snapshot_id you fetched yourself (e.g. via get_playlist) immediately beforehand, so a removal only ever applies to the playlist state you actually looked at. Never call this from a broad instruction like 'clean up my library' — only on an explicit, specific removal request the user approved for these exact items.
Inputs: uris (required), playlist_id (required), snapshot_id (required), confirm_token. Returns: The one return shape every write tool uses — see PLAN.md §2 on why a single con…
reorder_playlist_itemsAIdempotent
Move a contiguous slice of a playlist's items to a new position. range_start is the 0-based index of the first item to move, range_length how many items (default 1), insert_before the 0-based index to insert them at. Pins to the playlist's current snapshot if you don't supply one — if the playlist changed since you last looked, get_playlist_items first.
Inputs: playlist_id (required), range_start (required), insert_before (required), snapshot_id, +2 more. Returns: The one return shape every write tool uses — see PLAN.md §2 on why a single con…
replace_playlist_itemsAIdempotent
Replace a playlist's entire contents with a new list of URIs — the existing items are discarded. The preview shows what will be lost alongside what replaces it. Pass an empty list to clear the playlist entirely. For more than 100 URIs, the first 100 replace in one call and the rest are appended after.
Inputs: uris (required), playlist_id (required), confirm_token. Returns: The one return shape every write tool uses — see PLAN.md §2 on why a single con…
resolve_tracksARead-only
Resolve {artist, title} candidates to verified Spotify track URIs. Every input ends up in exactly one of resolved/unresolved — never silently substituted or dropped. Matching requires the artist to genuinely match (not just the title), which is what catches sped-up edits, karaoke covers, tribute recordings, and live versions that a title-only search would happily return instead of the real track. strict=true (default) only accepts exact/strong title matches; set false to also accept fuzzy 'weak' matches (still flagged as such) at the cost of precision. This tool has no opinion on what is currently popular — chart freshness is only as good as whatever produced the candidate list.
Inputs: candidates (required), strict. Returns: stats, resolved, unresolved
search_catalogARead-only
Search the Spotify catalog. limit is capped at 10 (Spotify reduced this from 50 in Feb 2026) and offset at 1000 — for more than 10 matches, page with offset rather than expecting a bigger single batch. Prefer field-filtered terms (track/artist/album/year/isrc) over free_text: bare title text reliably matches sped-up edits, live versions, karaoke covers, and tribute recordings instead of the real thing. There is no popularity or relevance score in the response — nothing here indicates what is currently popular or trending.
Inputs: isrc, year, album, limit, +5 more. Returns: albums, tracks, artists, playlists
server_statusARead-only
Report this server's own state: dry-run mode, Spotify authorization, granted OAuth scopes, whether destructive playlist removals are enabled, the local listening-history database's size and date range if built, and HTTP cache stats.
Inputs: no named parameters. Returns: dry_run, authorized, analytics_db, allow_removals, +3 more
set_playlist_coverA
Set a playlist's cover image from a local JPEG file. Spotify caps the encoded payload at 256 KB — this checks that before offering confirmation, so an oversized image fails fast with a clear message instead of a wasted round trip.
Inputs: image_path (required), playlist_id (required), confirm_token. Returns: The one return shape every write tool uses — see PLAN.md §2 on why a single con…
skip_statsARead-only
Skip-rate leaderboard grouped by artist, track, or month. Reports both the derived skip rate (reason_end='fwdbtn' AND played under the skip threshold) and the export's own raw 'skipped' field's rate side by side — they can disagree; see describe_listening_data. min_plays filters out low-sample noise.
Inputs: limit, group_by, min_plays. Returns: rows, group_by
taste_driftARead-only
Compare artist listening between two date periods (each [start, end] as YYYY-MM-DD) by share of total plays. Returns three lists: gained (no plays in period A, present in B), lost (present in A, none in B), held (present in both, ranked by the biggest change in share). This is how your taste drifted, by your own play counts — not an external trend signal.
Inputs: period_a_end (required), period_b_end (required), period_a_start (required), period_b_start (required), +1 more. Returns: held, lost, gained, period_a, +1 more
top_localARead-only
Ranked artists, tracks, or albums by play count or total listening time, optionally within a date range. This is YOUR local listening history, not a live popularity signal — Spotify removed those endpoints in 2026.
Inputs: end, limit, start, entity, +1 more. Returns: rows, entity, metric
update_playlist_detailsAIdempotent
Update a playlist's name, description, and/or public/private visibility. Only the fields you pass are changed. The preview shows an old-to-new diff of just those fields.
Inputs: playlist_id (required), name, public, description, +1 more. Returns: The one return shape every write tool uses — see PLAN.md §2 on why a single con…
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 35 tools
Most tools target a distinct resource/action, and descriptions carefully separate near-misses like get_playlist vs get_playlist_items and get_top_artists vs top_local. A few analytics tools (dropped_artists, taste_drift, rediscover_tracks) share a similar 'what did I stop listening to' concept, but their time-window semantics are clearly differentiated.
Reads consistently use get_* and playlist mutations use verb_* patterns, but the analytics block mixes noun phrases like listening_summary, skip_stats, top_local, taste_drift, and dropped_artists. The naming is readable and grouped by domain, but it is not a single predictable convention.
35 tools is well past the heavy range and creates a large selection surface for agents, even though the set is organized into Spotify reads, playlist writes, and local analytics. Some tools also overlap or subsume others, e.g., build_playlist_from_candidates wraps resolve + create + add, and query_listening_history could replace several named analytics tools.
Core workflows are well covered: catalog lookup, library inspection, full playlist lifecycle, and a rich local analytics layer with an SQL escape hatch. The main gaps are playback control (play/pause/skip/seek) and library removal operations (unsave tracks/albums, unfollow artists), which are secondary to this server's data-and-playlist-management focus.
Maintenance
Related MCP Connectors
Connect Claude to your Platform7n workspaces: chat, links, work and decks. One-click OAuth.
Connect Claude to your Platform7n workspaces: chat, links, work and decks. One-click OAuth.
Find, read, create and edit Plainer files with Claude Code or Codex. Approve access in your browser.
Lets Claude, ChatGPT, and Muse read and update your beckett tasks, notes, calendar, and lists.
Related MCP Servers
- FlicenseDqualityDmaintenanceEnables Claude to interact with Spotify by searching songs, creating playlists, getting recommendations, and managing your music through your Spotify account.73-
- AlicenseNot gradedqualityNot gradedmaintenanceConnects Claude to Spotify for music discovery, playlist creation, and collection analysis through natural language. Enables searching songs, analyzing music diversity, creating playlists, and getting recommendations using Spotify's API.-
- AlicenseNot gradedqualityDmaintenanceEnables Claude to control Spotify features including playback control, playlist management, search, and accessing user's listening history and preferences through the Spotify API.1ISC
- AlicenseNot gradedqualityDmaintenanceConnects Claude to Spotify, enabling play control, playlist management, lyrics retrieval, and music recommendations through natural language.1MIT