Skip to main content
Glama
spotify-mcp

spotify-mcp

by Stipe15

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

  1. 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.

  2. Register the redirect URI. In the app's settings, add exactly:

    http://127.0.0.1:8888/callback

    (If you change SPOTIFY_REDIRECT_PORT in step 4, update this to match.)

  3. Install dependencies (requires uv):

    uv sync
  4. Configure. Copy .env.example to .env and paste in your Client ID. The rest of the file is commented — the defaults are sensible for personal use, but at minimum consider setting SPOTIFY_MCP_TIMEZONE (see Local analytics below).

    cp .env.example .env
  5. Authorize. Opens your browser for a one-time Spotify login and saves a refresh token locally:

    uv run spotify-mcp login
  6. Wire 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 ./fixture

This 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-export

This 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.py

This 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

<user config dir>/spotify-mcp/token.json (Windows: %LOCALAPPDATA%\spotify-mcp\token.json)

Listening-history DB

<user data dir>/spotify-mcp/listening.duckdb

Resolver cache

<user data dir>/spotify-mcp/resolver_cache.duckdb

Write audit log

<user data dir>/spotify-mcp/audit.jsonl

HTTP ETag cache

<user cache dir>/spotify-mcp/http_etag_cache.sqlite3

Logs

stderr, JSON lines (stdout is reserved for the MCP protocol)

diagram

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 tools
add_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_dataA
Read-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_artistsA
Read-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_tracksC
Read-only

An album's tracklist.

Inputs: album_id (required), limit, offset. Returns: href, next, items, limit, +3 more

get_artistA
Read-only

Full metadata for one artist by its Spotify id.

Inputs: artist_id (required). Returns: GET /artists/{id}. No `followers`, no `popularity`.

get_artist_albumsB
Read-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_artistsA
Read-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_meA
Read-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_playlistsC
Read-only

Playlists the user owns or follows.

Inputs: limit, offset. Returns: href, next, items, limit, +3 more

get_playback_stateA
Read-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_playlistA
Read-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_itemsA
Read-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_playedA
Read-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_albumsB
Read-only

Albums saved to the user's library, most recently added first.

Inputs: limit, offset. Returns: href, next, items, limit, +3 more

get_saved_tracksA
Read-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_artistsA
Read-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_tracksA
Read-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_trackA
Read-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_hourA
Read-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_summaryA
Read-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_historyA
Read-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_tracksA
Read-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_itemsA
Destructive

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_itemsA
Idempotent

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_itemsA
Idempotent

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_tracksA
Read-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_catalogA
Read-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_statusA
Read-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_statsA
Read-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_driftA
Read-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_localA
Read-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_detailsA
Idempotent

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

    B3.3/5.0

    Scored across 35 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Connects 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.
      -