SpotifyMCP
This server gives an AI assistant full control over Spotify: playback, search, library, playlists, and profile management via the Web API.
Playback: get now playing/current state, play/pause, skip/previous, seek, set volume/shuffle/repeat, view and add to queue, list and transfer devices.
Search & catalog: search tracks, artists, albums, playlists, shows, episodes; get details for tracks, artists, albums, shows, episodes, audiobooks, and chapters.
User profile & stats: get current user profile, top tracks/artists, and recently played.
Library management: get, save, remove, and check saved tracks, albums, shows, episodes, audiobooks; manage followed artists.
Playlists: list, create, update, get playlists, add/remove/reorder items, and manage cover images.
Convenience extras: search-and-play best match, pagination up to 500 items, dry-run previews, read-only mode, diagnostics, duplicate cleanup, and M3U/CSV import/export.
Provides tools for interacting with the Spotify Web API, enabling playback control, searching tracks, albums, artists, playlists, podcasts, and audiobooks, managing the user's library and playlists, and retrieving listening personalization data.
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., "@SpotifyMCP Play my Discover Weekly playlist on my office speakers."
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.
SpotifyMCP
Spotify Web API MCP: playback, library, playlists, search, podcasts. Not affiliated with Spotify.
A broad Spotify Web API tool surface, plus extras most servers skip. Registration-gated wrappers are explained rather than hidden; see Registration-gated endpoints for the generated list.
What you get by default, and what to do about the rest. A server started with no environment registers a curated surface — search, playback, playlists, library, following — sized so the tool list does not dominate the context window before you have typed anything. SPOTIFY_MCP_TOOLSETS=all registers the entire registry instead, and the stats.fm tools are opt-in with SPOTIFY_MCP_STATSFM=1. Both are one line in docs/configuration.md.
A server started with no SPOTIFY_MCP_TOOLSETS registers 131 tools (150,111 bytes of schema) — the curated default surface (#889). SPOTIFY_MCP_TOOLSETS=all registers all 562 tools, along with 17 fixed resources, 28 resource templates, and 14 prompts. Toolsets and production gates can trim a configured host further; both figures describe a real production tools/list after finalizers.
3.0 and later
3.0 was the release where the open issue list went to zero — every epic, every issue under it, every contradiction we turned up auditing ourselves. Most of that backlog was never "bugs" in the crashing sense; it was places where this server reported a value it had not actually checked, which is the only kind of wrong that is genuinely dangerous.
It also removed tools, because Spotify deleted the endpoints underneath them in February 2026 — including artist follows, which have no migration target at all.
🤖 Paste this to your agent
Copy the block below into Claude Code, Cursor, OpenClaw, or any coding agent — it will set SpotifyMCP up for you.
⚠️ Never paste your Spotify credentials into a chat. Spotify's Developer Terms treat the Client ID as a credential: §VI.1.1 groups "I.D.s, client I.D.s, keys, passwords, security codes, or tokens" together as Security Codes, §VI.1.3 forbids disclosing them to any other party, and §VI.1.4 makes you responsible for their confidentiality. Anything you type into a conversation is retained by the model provider, written to shell history, and carried in the agent's context window. The Client ID is the only credential this server needs, and it is a Security Code rather than a public identifier — treat it like a password.
Set up the Spotify MCP server from https://github.com/NovaLux12/spotify-mcp-server. 1. Walk me through creating a Spotify app at https://developer.spotify.com/dashboard with redirect URI http://127.0.0.1:8888/callback. Point me at where the dashboard shows the Client ID, then stop — I will copy it myself. 2. Clone and build: git clone https://github.com/NovaLux12/spotify-mcp-server.git cd spotify-mcp-server && npm ci && npm run build 3. Show me which file my MCP host reads server environment from. The host's server config is the one that always works; a local .env is read only when you launch through this repo's npm run dev or npm start, which pass --env-file-if-exists on Node >=22.9 — the published binary does not read it. Print the exact line to add. I will type the Client ID in myself. Do not ask me for it and never echo it back. 4. Start the server and run the auth command yourself, then finish the browser login when it opens. This server uses PKCE, so there is no client secret and no credential to fetch beyond the Client ID. 5. Verify with the read-only spotify_doctor tool and report its rows.
Why this one
Complete | Playback, search, catalog, library, playlists, following, plus extras like duplicate cleanup, M3U/CSV import-export, podcast sessions, snapshot diffing, listening analytics, market checks, stats.fm taste reads, and taste composite briefs, playlists, and reports. |
Safe |
|
Honest about the surface | Tools that turn your listening history into derived metrics — hourly histograms, weekday profiles, discovery ratios — are off unless you ask for them with |
Honest | No tool claims to work when it cannot. Gated endpoints keep their wrappers, read replacements where one exists, and explain the 403 in plain English instead of crashing — see Registration-gated endpoints, generated from |
Polished | Paginated (up to 500), podcasts first-class, device-aware playback, |
Related MCP server: Spotify MCP Server
Quick start
1. Create a Spotify app
Spotify Developer Dashboard → Create app → add this Redirect URI exactly:
http://127.0.0.1:8888/callbackCopy the Client ID.
2. Authenticate
SPOTIFY_CLIENT_ID=your_client_id_here npx -y @novalux12/spotify-mcp@latest authOpens a browser, saves tokens to ~/.spotify-mcp/tokens.json, auto-refreshes after.
Windows (Command Prompt):
set SPOTIFY_CLIENT_ID=your_client_id_here && npx -y @novalux12/spotify-mcp@latest authWindows (PowerShell):
$env:SPOTIFY_CLIENT_ID="your_client_id_here"; npx -y @novalux12/spotify-mcp@latest authWindows is supported for install and everyday use, and is not covered by CI. The commands above are the supported path, but the test suite runs on Linux only, so a Windows-specific regression would not be caught before release. See docs/platform-support.md for exactly what is and is not verified there, and what the known gaps are.
Headless / remote host:
SPOTIFY_HEADLESS=1 SPOTIFY_CLIENT_ID=your_client_id_here npx -y @novalux12/spotify-mcp@latest auth
# prints a URL → open it on any machine → paste the redirect backCheck: npx -y @novalux12/spotify-mcp@latest doctor — exit 0 means you're good.
3. Add to your MCP host
{
"mcpServers": {
"spotify": {
"command": "npx",
"args": ["-y", "@novalux12/spotify-mcp@latest"],
"env": { "SPOTIFY_CLIENT_ID": "your_client_id_here" }
}
}
}Restart the host. A hammer icon in the chat input means it's connected.
Claude Code (no JSON editing):
claude mcp add spotify -- npx -y @novalux12/spotify-mcp@latest
export SPOTIFY_CLIENT_ID=your_client_id_hereOpenClaw — ~/.openclaw/openclaw.json → mcp.servers:
"spotify": {
"command": "node",
"args": ["/path/to/spotify-mcp-server/dist/index.js"],
"cwd": "/path/to/spotify-mcp-server",
"env": { "SPOTIFY_CLIENT_ID": "your_client_id_here" }
}Any spec-compliant host works — same command/args/env shape under mcpServers or servers. If the host can't pass env vars, authenticate once beforehand; the token cache persists.
What you can ask
"What are my top tracks this month?"
"Make a late-night driving playlist"
"Add Blinding Lights to my workout playlist"
"What podcasts have new episodes?"
"Clean duplicates across all my playlists"
"What does my taste look like? Build a playlist from it"
"Do my stats.fm lifetime genres match what I've played this month?"
Configuration
All via env vars — no config file. Only SPOTIFY_CLIENT_ID is required.
Variable | Example | Purpose |
| unset | Trim by group for hosts that cap tool counts. Unset registers the curated default surface; |
|
| Register the 50 stats.fm-backed tools across four registration keys — |
|
| Hide write-capable modules; read-only resources and prompts remain available. |
|
| Log mutations to JSONL for undo and audit. |
|
| Persist mutation receipts so |
|
| Turn off the "Music data supplied by Spotify" footer and the per-row |
Full reference: docs/configuration.md
spotify_doctor (CLI + in-server tool) diagnoses token state, scope gaps, Premium gating, rate-limit cooldowns, request/quota usage (cumulative + rolling-window counts, #904), and read-cache pressure (entries held, bytes retained, responses too large to cache, #894) without extra setup.
Upgrading to 2.0
2.0 is a contract release. One tool name is gone, four things moved, and one guarantee tightened:
get_show_episodesis removed. Uselist_show_episodes(same endpoint, same arguments, minus the drifted alias). It was the only name that changed; everything else in the surface keeps its name. The exact registry totals are generated at the top of this file, so this sentence deliberately carries no count of its own to fall behind.Destructive writes fail closed. Any confirmation-gated bulk write now refuses when the client cannot elicit, instead of proceeding unprompted.
archive_played_episodes'sconfirm: trueno longer authorises the delete (it is still accepted, and every result says it was ignored). For headless automation, setSPOTIFY_MCP_CONFIRM=neverdeliberately.Playlist set-operation inputs are canonical. A/B pairs are
playlist_a/playlist_b; ordered lists areplaylists;playlist_subtracttakes the base asbase_playlist_id. This was the 2.0 contract; the old spellings it was allowed to keep alongside it were withdrawn in 3.0 (#1287). They are no longer in any tool's schema, and a call that still sends one is refused before any Spotify request with avalidationerror whosereasonisretired_input, naming both what was sent and what to send instead. Each tool declared exactly one alias pair or one alias list, so the table below is a per-tool migration map rather than a bundle:family
canonical
the spelling that tool used to declare
A/B pair
playlist_a,playlist_ba/b, orplaylist_id_a/playlist_id_b, orplaylist_a_id/playlist_b_id— one of them, per toolordered list
playlistsplaylist_ids, orsource_playlist_ids, orsources— one of them, per toolsubtraction
base_playlist_id+playlistssubtract_playlist_ids, or the positional formplaylists: [base, ...sources]— one of them, per toolbase_playlist_idis required again: with the positional form gone there is no longer a base for a caller to omit. A name the tool does not declare, and is not a retired spelling, is anunknown_paramerror — a different claim fromretired_input, which says the server published that name until 3.0.Numeric caps have canonical names.
max_resultscaps what is returned;limitandscan_capcap how much of each source is read.Unknown arguments are rejected with a typed
unknown_paramerror rather than ignored, so a renamed parameter fails loudly instead of silently doing nothing.
Run spotify_doctor after upgrading: it reports the registered surface, the
gates that hid modules, and the granted scopes in one call.
Docs
docs/v3-roadmap.md — what's coming in 3.0, and the one bug underneath all of it
docs/migration-v3.md — every retired name in 3.0 and what replaced it, including the one operation with no replacement
SPEC.md — every tool, resource & prompt
ARCHITECTURE.md — how it's built
docs/configuration.md — all env vars
docs/cli.md —
tools,call,watch,export,init: the CLI as an MCP clientdocs/schema-budgets.md — per-module schema budgets and registration order
docs/statsfm.md — stats.fm second source: setup, tool cheat sheet, gotchas
docs/cookbook.md — copy-paste agent recipes
docs/non-goals.md — what v2 will not do, why, and what it offers instead
docs/taste.md — anonymized taste showcase driving a playlist
docs/wave2-composites.md — read-only taste composites
docs/distribution.md — distribution and release notes
docs/faq.md — auth, Premium, 403s, headless, tokens
docs/compliance.md — brand marks, attribution & the outbound
User-AgentCONTRIBUTING.md — dev setup & conventions
CHANGELOG.md — release history
Requirements
Premium for playback control (play/pause/skip/seek/volume/queue). Free accounts can still use search, library & playlists.
Node 22.9+, Spotify app in dev mode (5 users until extended quota).
Audiobooks gated by Spotify to US/UK/CA/IE/NZ/AU.
A subset of endpoints is registration-gated — 403 on current app registrations regardless of scopes or Premium. Whether a grandfathered registration still answers
200is unverified (#1338). This is a property of your app registration, not of the tool. See Registration-gated endpoints.
Registration-gated endpoints
Some Web API endpoints are denied at the app-registration level: on current Spotify app registrations they return 403 Forbidden no matter which OAuth scopes you grant or whether the account is Premium. This is Spotify-side gating, not a misconfiguration on your end.
Nothing here is simply "removed". Three sources describe this class and they do not agree, which is why the table below states the runtime behaviour instead of a verdict:
Spotify's February 2026 changelog marks a batch of operations
[REMOVED].The live OpenAPI schema still publishes most of those same paths, carrying
deprecated: truerather than deleting them —/artists/{id}/top-tracksand all sevenGet Severalbatch paths among them.The runtime truth is neither document: it is what your app registration is allowed to read. A registration without the grant answers
403/404/410. Whether a grandfathered registration still answers200is unverified (#1338): no probe in this repository shows it, and the one probe artefact that was once cited for it records403on every such path.
So a 403 here is a property of the registration, not of the tool. No tool is hidden for being gated, no gated tool is a zombie: each one either reads a documented replacement and answers, or makes the call and explains the 403 in plain English. The authoritative list is the GATED_FAMILIES array in src/gating.ts — GATED_PATH_PATTERNS is derived from it, so the classifier and this table cannot drift apart.
Endpoint family | Shipped tools that call it | On a current registration |
|
| 403 explained |
| (none — no shipped tool reads this path) | Replaced; no call site |
|
| 403 explained |
|
| 403 explained |
|
| 403 explained |
| (none — migrated to | Replaced; no call site |
| (none — migrated to | Replaced; no call site |
|
| Replaced with per-id reads |
All 8 families above are operations Spotify's February 2026 changelog marks [REMOVED].
Confirm the list yourself against the source of truth:
grep -n "id: '" src/gating.ts # the families, with tools and fallback per rowNotes:
A family in that list is a runtime classifier, not a promise that a tool calls it. Three families (
browse-new-releases,me-type-contains,playlist-followers-contains) have no live call site left — the tools that used them were migrated onto replacements — and their patterns are retained so a future caller is still covered by the 403 contract rather than silently losing it.GET /me/library/containsis not gated (it returned 200 on the same probe) and backs the saved-state reads behindcheck_playlist_following,restore_library_snapshotand receipt verification. Thecontainsfamilies above are the documented per-type checks, which the changelog marks removed in favour of this one. (The playlist duplicate-cleanup tools are not in that set — they page/playlists/{id}/items.)Batch fallback (#725). When a
Get Severalbatch endpoint answers 403,fetchSeveralretries through per-idGET /<kind>/{id}calls on the client's existing queue/backoff. Per-id paths are not in the gated class, so the read still succeeds. The response carriesdegraded: trueand a[degraded: batch endpoint returned 403; … fetched individually]footer in prose, plusdegraded_reasoninstructuredContent, so a caller can tell a per-item round-trip from a clean batch read.Endpoints Spotify lists as removed that this server does not wrap at all (no shipped tool, so nothing to explain):
/recommendations,/recommendations/available-genre-seeds,/me/apps,/me/chapters, the/artists/{id}/related-artists,/audio-features,/audio-analysisand/browse/featured-playlistsreads, and the/playlists/{id}/tracksfamily (superseded by/playlists/{id}/items). These are absent from the table above because absence of a tool is the honest answer for them — there is no 403 to explain.
"Not authenticated" → re-run
auth; check~/.spotify-mcp/tokens.jsonexists and the redirect URI matches exactly (no trailing slash).Auth loop / S256 error → open a private window, log into spotify.com first, then retry the auth URL there.
Port in use (8888) → free the port, set
SPOTIFY_REDIRECT_URIto another port, or useSPOTIFY_HEADLESS=1. The message namesEADDRINUSEand the port because the usual cause is a previousauthstill holding it.Timed out waiting for the browser callback → not a port conflict; the listener bound and has been closed. Retry, and check the redirect URI is registered exactly. Bound it with
SPOTIFY_AUTH_TIMEOUT_MS(default 5 min)."Premium required" on playback → expected on Free accounts; no workaround.
Forbiddenon lookup tools (categories, markets, top-tracks, user profiles, the per-typecontainschecks) → these endpoints are registration-gated by Spotify; see Registration-gated endpoints. (GET /me/library/containsis not one of them, so a 403 there is a real problem, not a gated registration.)Still stuck?
npx -y @novalux12/spotify-mcp@latest doctoror ask your agent to run the spotify-mcp-doctor skill.
What this server is not
v2 has a written non-goals list, so a request for something outside it gets an answer rather than a maybe. Each entry below carries its reasoning in SPEC §1, and docs/non-goals.md is the record behind both: what each one rules out, the source it rests on, and what the server offers instead.
Audio streaming, audio analysis, and offline playback
A web UI, a dashboard, or an MCP UI surface
Multi-tenant or hosted operation
Sharing one user's credentials across users
Lyrics
The Spotify Connect SDK and native client integration
Voice control
Training a model on Spotify data, or exporting derived profiles
A second third-party upstream, ad-tech, or monetization egress
Working around Spotify's own controls
Development
git clone https://github.com/NovaLux12/spotify-mcp-server.git && cd spotify-mcp-server
npm ci && npm run build
cp .env.example .env # add your Client ID
npm run auth # one-time login
npm run dev # run from source
npm test # unit + MCP smoke testsNot affiliated with Spotify. Use per the Spotify Developer Terms.
MIT © Carme99 and NovaLux12 contributors · Acknowledges calebWei/SpotifyMCP and varunneal/spotify-mcp.
Available Tools
131 toolsadd_to_playlistB
Add tracks or episodes to a playlist. Max 100 URIs per call.
Inputs: uris (required), playlist_id (required), dry_run, position, +1 more.
add_to_queueA
Add a track or episode to the end of the playback queue.
Inputs: uri (required), dry_run, device_id, response_format.
apply_sceneA
Apply a saved scene: resolve its device hint, transfer playback, then set volume/shuffle/repeat and start the saved context (in that order; missing targets are skipped)
Inputs: name (required), dry_run, response_format.
audiobook_progressA
Audiobook progress rollup: chapters total, played count, current chapter, percent complete. Walks every chapter page up to the shared fetch-all cap and reports scan coverage. Quota: 1 audiobook GET + chapter page GETs.
Inputs: audiobook_id (required), market, response_format.
backup_firstA
Create a pre-flight library snapshot before a destructive operation. Returns snapshot file path and counts for later restore. Read-only against Spotify.
Inputs: notes, response_format.
backup_libraryARead-onlyIdempotent
Snapshot your ENTIRE library to a local JSON file (read-only against Spotify): liked tracks, saved albums/shows/episodes/audiobooks, followed artists, and every playlist with its items. Walks capped at SPOTIFY_MCP_FETCH_ALL_CAP (500/category) and each playlist at SPOTIFY_MCP_PLAYLIST_ITEMS_CAP (500); the smaller wins, so a full backup of a large playlist needs both raised. Files land in SPOTIFY_MCP_BACKUP_DIR (default ~/.spotify-mcp/backups), mode 0600.
Inputs: notes, dry_run, walk_cap, response_format.
batch_add_to_playlistA
Add tracks from multiple source URIs (tracks, albums, artists, playlists) to a target playlist in one call. Dedupes within the batch and optionally against the existing playlist. Batches writes in groups of 100. Dry-run previews without writing. Elicitation for 100+ tracks. Target the playlist by ID/URI/URL or by lane name.
Inputs: source_uris (required), limit, dedupe, dry_run, +5 more.
call_toolADestructive
Call any REGISTERED tool by name — the dispatcher that makes a trimmed surface usable. find_tool discovers a name, inspect_tool shows its schema. Reaches only tools this session registered; for anything else use enable_toolset. Refuses to call itself.
Inputs: name (required), arguments. Returns: object
cancel_wind_downA
Cancel the in-process wind-down ramp, if one is running
Inputs: device_id, response_format.
check_following_artistsARead-onlyIdempotent
Check if the user follows specific artists — this tests FOLLOW state, not library-saved state (for that use check_in_library). Accepts IDs or spotify:artist: URIs. Rows carry {id, uri, follows}; returns a boolean per ID. Max 50.
Inputs: ids (required), max_results, response_format.
check_in_libraryARead-onlyIdempotent
Preferred. Accepts the widest URI mix (track, album, episode, show, audiobook, artist, user, playlist) in one request. Check whether items are saved in or followed by the user — this tests LIBRARY-SAVED/FOLLOWED state, distinct from check_following_artists which only tests artist FOLLOW state. Returns a boolean per URI via Spotify's unified endpoint. Max 40. Following an artist is no longer expressible: Spotify's February 2026 changes removed PUT/DELETE /me/following, and this endpoint's save side does not accept spotify:artist: URIs, so there is no endpoint that can follow or unfollow an artist. This read still answers the question for artist URIs.
Inputs: uris (required), max_results, response_format.
check_playlist_followingARead-onlyIdempotent
Check if you follow 1–50 playlists. Follow state: GET /me/library/contains?uris=spotify:playlist:,… (40/req, 1–2 GETs). Unreadable state reports unknown, never not-followed.
Inputs: playlists, max_results, response_format.
clean_all_playlistsADestructive
Scan every playlist in your library for duplicate items (repeated URIs, and on opt-in same-song copies under different URIs when match_by=name_artist). Reports per-playlist findings by default; pass apply=true to remove them (keeps the first occurrence of each group). Bulk removals ask for one confirmation before anything is deleted. See the duplicate-matching vocabulary in SPEC section 4.
Inputs: apply, dry_run, match_by, max_results, +2 more.
clean_backup_artifactsADestructive
Delete the NON-library files sharing SPOTIFY_MCP_BACKUP_DIR with your library backups: closed listening sessions (listening-session-*.json), playlist write pre-images (playlistops-pre-*.json) and legacy or migrated playback bookmarks (playback-bookmark-*.json). Library backups and their .meta.json sidecars are never touched — use delete_backup, and naming one here is refused. These files are local and gone for good once deleted. Preview by default; executing is confirmation-gated and refused when the client cannot prompt (SPOTIFY_MCP_CONFIRM=never bypasses). Ages are mtimes, and the default window is SPOTIFY_MCP_BACKUP_ARTIFACT_RETENTION_DAYS — separate from the library window. Unrecognised files are listed, not deleted.
Inputs: files, family, dry_run, older_than_days, +1 more.
clone_playlist_coverB
Copy cover image from source playlist to target. Quota: GET images + PUT images (plus image fetch).
Inputs: source_playlist_id (required), target_playlist_id (required), dry_run, image_index.
compare_playlist_coversARead-onlyIdempotent
Compare two playlists covers: URL equality, dimensions. Quota: 2 GETs.
Inputs: limit, scan_cap, playlist_a, playlist_b, +2 more.
copy_playlistA
Duplicate an existing playlist into a new playlist, preserving track order. Creates the new playlist then adds tracks in batches of 100. Dry-run reports what would be created.
Inputs: new_name (required), source_playlist_id (required), limit, public, +6 more.
create_playlistA
Create a new playlist for the current user. Set dry_run=true to preview without creating.
Inputs: name (required), public, dry_run, description, +1 more.
create_smart_playlistA
Create a playlist from rules over your own listening data: top tracks (by time range), recently played, or saved tracks — with optional artist-name filtering and a one-track-per-artist toggle. When source=saved_tracks the pool is the newest N saved tracks (N=scan_cap, default fetchAllCap=500) and truncation is reported. No deprecated recommendations endpoints involved. Every source has a pool ceiling (top_tracks 100, recently_played 50, saved_tracks scan_cap), reported as pool_capped with pool_cap — a capped pool is a floor, not a complete scan. dry_run previews the exact track list without creating anything.
Inputs: name (required), limit, public, source, +7 more.
delete_backupADestructive
Delete one library backup file (and its metadata sidecar) from SPOTIFY_MCP_BACKUP_DIR. Irreversible — the library rows in the file cannot be recovered from anywhere else. Destructive and confirmation-gated: dry_run defaults to true, and executing is refused when the client cannot prompt (SPOTIFY_MCP_CONFIRM=never bypasses). Paths outside the backup directory are refused.
Inputs: file (required), dry_run, response_format.
delete_sceneADestructive
Delete a saved playback scene from the local sidecar
Inputs: name (required), response_format.
diff_playlistsARead-onlyIdempotent
Compare two playlists up to the configured source cap: tracks only in A, only in B (by track ID), and tracks present in both but at different positions. Rendered rows are capped by max_results; truncation metadata reports when source walks hit scan_cap.
Inputs: limit, dry_run, scan_cap, playlist_a, +3 more.
enable_toolsetA
Register an inactive toolset into THIS session and emit the MCP tools-list-changed notification — widens the surface without a restart. Takes the SPOTIFY_MCP_TOOLSETS vocabulary (all, core, playback, catalog, playlists, library, personalization, statsfm, taste, discovery, portability). Reverts entirely if it would breach the aggregate schema budget; refuses a module SPOTIFY_MCP_READONLY hides.
Inputs: sets (required). Returns: object
expand_mood_to_queriesA
Turn a free-text listening mood into search terms (genres, keywords, terms to avoid) for search. Uses the host model via MCP sampling when the host advertises the sampling capability; otherwise returns a built-in static map. Calls no Spotify endpoint and changes nothing. A model reply that cannot be parsed returns isError after one retry — it is never replaced by a guess.
Inputs: mood (required), max_tokens, response_format.
export_all_playlistsA
Export every owned (or all) playlist with metadata + items to a sidecar file. Quota: GET /me/playlists + N×GET /playlists/{id}/items; capped by fetchAllCap.
Inputs: scope, format, output_dir, include_items, +1 more.
export_followed_artistsA
Export your followed artists to a local directory as JSON or CSV. Fields: uri, name, genres. The file's exported_at is the export time, not a per-artist follow date (Spotify does not expose followed_at).
Inputs: format, output_dir, response_format.
export_library_jsonA
Export your full library (saved tracks, albums, shows, episodes, audiobooks) to a local directory as JSON or CSV sidecar files. Respects SPOTIFY_MCP_FETCH_ALL_CAP per type; when capped, reports cap_reached + truncated and a prose footer ("first N of … — raise SPOTIFY_MCP_FETCH_ALL_CAP").
Inputs: format, output_dir, response_format.
export_listening_historyA
Export your listening history (recently played) to a JSON or CSV sidecar by walking /me/player/recently-played with before-cursor pagination. Respects SPOTIFY_MCP_FETCH_ALL_CAP; writes file 0600 and reports path + counts.
Inputs: after, limit, before, format, +3 more.
export_playlistA
Export a playlist's full item list as an M3U playlist file or a CSV spreadsheet. Pages every item; pass output_path to write a file (created with mode 0600) inside the configured output root, or omit it to get the document inline. CSV cells are formula-safe.
Inputs: playlist_id (required), format, overwrite, max_results, +3 more.
export_profile_stateA
Export local sidecar stores (scenes, genre-tags, playback-ext, search-history, mutations, artist-watchlist) to a single schema-versioned JSON archive. artist-watchlist is ~/.spotify-mcp/artist-watchlist.json; SPOTIFY_MCP_DATA_DIR overrides that directory.
Inputs: output_dir, include_history, response_format.
filter_by_genreARead-onlyIdempotent
List URIs of your saved tracks or albums whose artists carry a given genre tag (case-insensitive tag-name match against your sidecar). Output is directly usable as create_playlist / add_to_playlist input. Read-only.
Inputs: kind (required), genre (required), max_results, response_format.
find_duplicate_saved_tracksARead-onlyIdempotent
Read-only duplicate detection over your saved (liked) tracks. Exact groups require the same non-null ISRC and album id with duration within ±2s, and keep the oldest dated save. On opt-in, near-duplicate groups show same-title/artist tracks whose ISRC, release, or duration differs; these are distinct saved tracks and are review-only with no removals. Undated saves sort after dated saves. Optionally pass a playlist_id to cross-reference which group members also appear in that playlist. Never mutates your library.
Inputs: max_results, playlist_id, response_format, include_near_duplicates.
find_duplicates_in_playlistARead-onlyIdempotent
Find duplicate tracks in a playlist under one published matching rule. match_by selects the rule (uri — the same track object twice; name_artist — same name and credited artists, catching relinks and remasters; name — same title only) and the rule is echoed back as match_by, so a group count is never unattributable. See the duplicate-matching vocabulary in SPEC section 4.
Inputs: playlist_id (required), match_by, max_results, response_format.
find_duplicate_tracks_across_playlistsARead-onlyIdempotent
Find tracks that appear in more than one of the given playlists (cross-playlist dupes). Quota: N GETs (one per playlist).
Inputs: playlists, max_results, response_format.
find_toolARead-onlyIdempotent
Search the live tool registry by name or description substring — the fastest way to discover which of the 500+ tools handles a job. Discovery set: find_tool/inspect_tool/toolset_report are always available (also via catalog). Use this first when unsure which verb to use (e.g., playlist vs snapshot vs search).
Inputs: query (required), limit, response_format. Returns: object
followed_playlists_auditB
Inventory of followed vs owned playlists: counts, collab, public, follower totals. Quota: GET /me/playlists paged.
Inputs: max_results, only_followed, response_format.
following_analyticsB
Followed-artist rollups from the tag sidecar; popularity/followers unavailable (Spotify no longer returns those fields). Quota: GET /me/following.
Inputs: top_n, group_by, max_results, response_format.
follow_playlistA
Follow a playlist — save it to your Spotify library — via PUT /me/library. Spotify removed the playlist-followers endpoints in Feb 2026; this is the only way to follow a playlist. Supports dry_run (default true); writes require confirmation unless SPOTIFY_MCP_CONFIRM=never.
Inputs: playlist_id (required), public, dry_run, response_format. Returns: ok, dry_run, receipt, cancelled
get_currently_playingARead-onlyIdempotent
Lightweight poll of what is playing right now: the item and progress only. For full session state (shuffle/repeat mode, active device, volume) use get_now_playing instead.
Inputs: market, response_format, additional_types.
get_devicesARead-onlyIdempotent
List available Spotify Connect devices. The same rows are readable as a resource with no tool call at spotify://player/devices ('?format=json' returns the raw API object).
Inputs: max_results, response_format.
get_followed_artistsARead-onlyIdempotent
Get the artists the user follows. fetch_all=true walks every page; limit/after page manually.
Inputs: after, limit, fetch_all, max_results, +1 more.
get_now_playingARead-onlyIdempotent
Full device/session state for what is playing right now — item, progress, plus shuffle/repeat mode, active device, and volume. For a lightweight item+progress poll use get_currently_playing instead.
Inputs: market, response_format, additional_types.
get_playlistARead-onlyIdempotent
Get a playlist's metadata (including cover image) and items. Use market to relink tracks and flag unavailable ones, and fields/additional_types to trim the payload — both are forwarded to the metadata read and the item pages.
Inputs: id, limit, fields, market, +6 more.
get_playlist_added_datesBRead-onlyIdempotent
List when each track was added to a playlist (added_at + added_by). Quota: GET /playlists/{id}/items paged.
Inputs: playlist_id (required), sort, max_results, response_format.
get_playlist_coverBRead-onlyIdempotent
Get a playlist's cover image URLs
Inputs: id, max_results, playlist_id, response_format.
get_playlist_itemsARead-onlyIdempotent
List a playlist's items on a single page. Use market to relink tracks and flag unavailable ones, and fields/additional_types to trim the payload.
Inputs: id, limit, fields, market, +6 more.
get_playlist_snapshotARead-onlyIdempotent
Expose snapshot_id + item count for optimistic concurrency. Quota: 2 GETs.
Inputs: playlist_id (required), max_results, response_format.
get_queueARead-onlyIdempotent
Read the playback queue. Use this for queue CONTENTS (what is playing, what is up next, how long it runs, what repeats). Use peek_next for a short lookahead. Quota: 1 read; view=enriched and include=runtime add one GET /me/player, and the context label adds one catalog read.
Inputs: view, include, max_results, response_format.
get_saved_albumsARead-onlyIdempotent
Get albums saved in the user's library. Set fetch_all=true to retrieve the entire collection. Output is capped by max_results (default: SPOTIFY_MCP_MAX_ITEMS).
Inputs: limit, market, offset, fetch_all, +2 more.
get_saved_countsARead-onlyIdempotent
Library size snapshot: counts for tracks/albums/shows/episodes/audiobooks/playlists via limit=1 reads — no item paging. The total covers library saves only: playlists are owned and followed collections, so their count is reported alongside the library rows and excluded from the total. A collection that could not be read (rate limited, gated, or erroring) is reported as unreadable with its reason and left out of the total — it is never reported as 0. One attempt per collection: a rate limit is surfaced, not retried. Quota: 6 GETs.
Inputs: response_format.
get_saved_episodesARead-onlyIdempotent
Get podcast episodes saved in the user's library. Set fetch_all=true to retrieve the entire collection. Output is capped by max_results (default: SPOTIFY_MCP_MAX_ITEMS).
Inputs: limit, market, offset, fetch_all, +2 more.
get_saved_showsARead-onlyIdempotent
Get podcast shows saved in the user's library. Set fetch_all=true to retrieve the entire collection. Output is capped by max_results (default: SPOTIFY_MCP_MAX_ITEMS).
Inputs: limit, offset, fetch_all, max_results, +1 more.
get_saved_tracksARead-onlyIdempotent
Get tracks saved in the user's Liked Songs. Set fetch_all=true to retrieve the entire collection. Output is capped by max_results (default: SPOTIFY_MCP_MAX_ITEMS).
Inputs: limit, market, offset, fetch_all, +2 more.
get_user_playlistsBRead-onlyIdempotent
List the current user's playlists
Inputs: limit, offset, fetch_all, max_results, +1 more.
get_user_playlists_by_idARead-onlyIdempotent
List another Spotify user's public playlists (paginated). Removed by Spotify's February 2026 Web API changes — unavailable for newer app registrations. Output is capped by max_results (default: SPOTIFY_MCP_MAX_ITEMS).
Inputs: user_id (required), limit, offset, max_results, +1 more.
get_user_profileARead-onlyIdempotent
Get any Spotify user's public profile (display name, profile image). Removed by Spotify's February 2026 Web API changes — unavailable for newer app registrations. The followers field was separately removed from user profiles, so no follower count is reported
Inputs: user_id (required), response_format.
grow_playlistA
Propose tracks to grow one of your playlists using ONLY your own listening data (no recommendations): finds tracks appearing in >=2 of your OTHER playlists, boosts ones sharing an artist with the target playlist, excludes tracks already in it (and optionally your saved library), and returns top candidates with evidence. Read-only: review the proposals, then call add_to_playlist with the URIs you want.
Inputs: playlist_id (required), size, dry_run, max_results, +2 more.
history_searchARead-onlyIdempotent
Search portability, backup and mutation-history stores; hits name their source. Quota: local only (no API).
Inputs: query, scope, response_format.
import_from_sidecarA
Additive restore from a library.json sidecar written by export_library_json: re-adds every missing saved item across all five collections (tracks, albums, shows, episodes, audiobooks) through the unified PUT /me/library endpoint, skipping items the library already holds. Rows whose uri is not a canonical spotify::<22-char id> URI are counted as invalid and never sent. Collections the file does not carry are named in absent_keys. The exporter's own truncated / cap_reached flags are surfaced as sidecar_truncated + truncated_collections: a capped sidecar restores only the rows it holds and says so, and a file with no flag reports completeness as UNKNOWN rather than complete. The prompt and the result both state the sidecar path, the date the file itself declares (exported_at, or the named reason it declares none — never the mtime), the row count, the one use being made of it, and whether a human confirmed that use (see consent_note). dry_run=true by default. Quota: local read + contains-check + chunked writes when dry_run=false.
Inputs: dry_run, input_path, response_format.
import_playlistA
Parse an M3U or CSV document (the inverse of export_playlist) and append its Spotify URIs to a target playlist. Pass the document inline via content, or read it from input_path (a regular file inside the configured read roots). URIs already in the playlist are skipped, so a re-run adds nothing. Adds in batches of 100. Use dry_run=true to preview without writing. Result records the document source and the use made of it (consent_note); under 100 new URIs nothing is gated.
Inputs: playlist_id (required), format, content, dry_run, +2 more.
import_profile_stateA
Restore local sidecar stores from a profile-state archive. merge unions each store on its own keys and de-duplicates search_history by entry id; overwrite replaces each store, keeping a 0600 .bak of what it replaced. The mutation ledger (stores.mutations_history) is export-only: it is never appended to or replaced, and an archive carrying it is reported as skipped. dry_run reports the per-store plan and writes nothing. Refuses newer schema versions.
Inputs: input_path (required), mode, dry_run, response_format.
inspect_toolARead-onlyIdempotent
Show one tool's full description and input schema before calling it
Inputs: tool_name (required), response_format. Returns: object
library_genre_reportARead-onlyIdempotent
Aggregate your saved library by user-declared genre tags. Scans all saved tracks and albums, joins each item's artists against your tag sidecar (see tag_management), and reports per-genre track/album counts plus the contributing artists. Genres are unavailable from Spotify itself, so only artists you have tagged appear here.
Inputs: max_results, response_format.
library_hygieneA
Read-only album hygiene over your liked tracks: flags near-complete albums worth saving and lone singles with nothing else liked from their artist (low confidence). Album totals come from the /me/tracks walk; a width-bounded per-id GET /albums/{id} fills in the rest. Never mutates. dry_run previews cost.
Inputs: dry_run, max_results, response_format.
library_snapshot_diffA
Diff two sidecar JSON files (library.json or playlists.json): added/removed counts + samples. Quota: local only (no API).
Inputs: after_path (required), before_path (required), response_format.
list_accountsARead-onlyIdempotent
List every local account this server can act as, and which one it is acting as now. Returns each account's account_id, profile name, display name and token file PATH — never any token material. Reads the local registry and one GET /me for the acting account; no mutation requests are issued.
Inputs: response_format.
list_backupsBRead-onlyIdempotent
List complete and partial library backups (newest first) using bounded metadata sidecar reads, with a bounded prefix fallback for legacy snapshots. Expires snapshots past SPOTIFY_MCP_BACKUP_RETENTION_DAYS (default 30, 0 disables) and reports what it removed, plus the store envelope (dir_bytes, oldest_created, oldest_retention_until).
Inputs: response_format.
list_scenesBRead-onlyIdempotent
List saved playback scenes from the local sidecar
Inputs: response_format.
merge_playlistsA
Merge multiple playlists into one. Deduplicates tracks across sources (first-seen order wins) and adds them in batches of 100. Pass target_playlist_id to append to an existing playlist (it is NOT cleared) or new_name to create a fresh playlist.
Inputs: limit, public, dry_run, new_name, +5 more.
move_items_between_playlistsA
Bulk rehome items between playlists. Mode copy keeps the source intact; mode move removes from source after copying — by playlist position, removing exactly the transferred occurrences and leaving any other copy in the source. Supports dedupe against target and optional name/artist filter. Either side may be named by lane.
Inputs: mode, limit, dedupe, filter, +8 more.
overlap_playlistsB
Find tracks shared across playlists: reports how many playlists each track appears in and lists tracks present in at least min_overlap playlists (default: all of them), most-shared first.
Inputs: limit, dry_run, scan_cap, playlists, +3 more.
pauseB
Pause playback on the active device
Inputs: dry_run, device_id, response_format.
pin_playlistA
DEPRECATED, use follow_playlist. This tool never pinned anything; it has always saved the playlist to your Spotify library via PUT /me/library.
Inputs: playlist_id (required), public, dry_run, response_format. Returns: ok, dry_run, receipt, cancelled
plan_podcast_sessionARead-onlyIdempotent
Greedy-pack your saved podcast episodes into a listening session of a given length. Episodes play their remaining time (duration minus resume position); fully played ones are skipped. Scanning stops at the first unplayed episode that doesn't fit.
Inputs: minutes (required), kind, market, saved_only, +2 more.
playC
Start or resume playback. Optionally target specific content.
Inputs: uris, offset, dry_run, device_id, +4 more.
play_from_searchA
Search Spotify by name and immediately play the best match. Works for songs and podcast episodes — no URI needed.
Inputs: query (required), market, dry_run, device_id, +2 more.
playlist_collab_toggleB
Toggle collaborative/public flags (guards public=true && collaborative=true 400). Quota: GET + PUT.
Inputs: playlist_id (required), public, dry_run, collaborative.
playlist_reverseA
Reverse a playlist in one atomic replace. Quota: GET all + PUT/POST.
Inputs: playlist_id (required), dry_run.
playlist_shuffleB
Fisher-Yates shuffle a playlist (seeded optional). Quota: GET all + PUT/POST.
Inputs: playlist_id (required), seed, dry_run.
playlist_sortA
Sort a playlist in place by added_at/name/artist/duration. Quota: GET all + PUT/POST. popularity is not a sort key: the API no longer returns it on playlist items.
Inputs: playlist_id (required), dry_run, sort_by, max_results, +1 more.
playlist_subtractB
Remove tracks of B..N from A by REWRITING A: one PUT replaces every row with the ones that survive, so any row of A absent from the union is DELETED, and the rows that remain are re-written in order. Subtracting every track empties A via one PUT with an empty uris array (Spotify's documented clear); a reply with no snapshot_id reports unconfirmed, not ok. Quota: N GETs + PUT.
Inputs: base_playlist_id (required), limit, dry_run, scan_cap, +3 more.
playlist_symmetric_differenceB
Tracks in exactly one of two playlists (XOR). Quota: 2 GETs.
Inputs: limit, scan_cap, playlist_a, playlist_b, +2 more.
playlist_template_applyB
Create an instant mood/vibe playlist from a template (focus, wind-down, gym, commute) composed from your existing listening data. Creates a new playlist and fills it.
Inputs: template (required), name, limit, public, +3 more.
playlist_to_libraryA
Save all tracks of a playlist to your Liked Songs (library). Quota: GET playlist items + PUT /me/tracks (chunked 50).
Inputs: playlist_id (required), dedupe, dry_run, response_format.
playlist_trimB
Trim playlist to N items (keep first/last/random) by OVERWRITING the playlist: every row outside the kept set is DELETED, and the kept rows are re-written in the new order. An overwrite that deletes rows asks for confirmation first. Quota: 2 walks of the playlist items + 2 metadata GETs + PUT/POST.
Inputs: keep (required), playlist_id (required), dry_run, keep_which.
playlist_unionB
Union of 2–10 playlists into target (deduped, first-seen order). An empty union empties the target the same way subtract does. Quota: N GETs + PUT/POST; replacing an existing target also reads its current items and its playlist metadata to measure the destructive impact.
Inputs: limit, dedupe, dry_run, scan_cap, +5 more.
remove_duplicate_playlist_itemsADestructive
Remove duplicate items from a playlist: keeps the first occurrence of each track and removes later repeats, under the match_by rule the other duplicate tools use — uri (default, exact repeats), name_artist (same name and credited artists, catching remasters and relinks under a new URI) or name (same title only). The rule applied is echoed as match_by. Supports dry_run; removals of 10+ items ask for confirmation via elicitation. See the duplicate-matching vocabulary in SPEC section 4.
Inputs: playlist_id (required), dry_run, match_by, include_relinked.
remove_from_libraryADestructive
Preferred. Accepts the widest URI mix (track, album, episode, show, audiobook, user, playlist) in one request. Remove one or more items from the user's library via Spotify's unified library endpoint. Max 40. PREVIEWS BY DEFAULT — pass dry_run=false to commit. Removals of 10+ items additionally require elicitation confirmation (or SPOTIFY_MCP_CONFIRM=never for automation).
Inputs: uris (required), dry_run, response_format.
remove_from_library_by_playlistADestructive
Remove from Liked Songs any tracks that also appear in a given playlist. Quota: 2 GETs + DELETE (chunked). PREVIEWS BY DEFAULT — pass dry_run=false to commit. Removing 10+ saved tracks additionally requires elicitation confirmation (or SPOTIFY_MCP_CONFIRM=never for automation).
Inputs: playlist_id (required), dry_run, response_format.
remove_from_playlistBDestructive
Remove tracks or episodes from a playlist. Max 100 entries per call.
Inputs: uris (required), playlist_id (required), dry_run, snapshot_id.
reorder_playlist_itemsA
Move a range of items within a playlist. Spotify semantics: when insert_before > range_start, the effective destination shifts down by range_length because the moved range is lifted out first (e.g. moving [2] to insert_before=4 lands it AT index 3).
Inputs: playlist_id (required), range_start (required), insert_before (required), dry_run, +1 more.
replace_playlist_itemsADestructive
Replace ALL items in a playlist with the supplied URIs, overwriting the current contents. Lists longer than 100 URIs are sent in chunks internally (replace + appends).
Inputs: uris (required), playlist_id (required), dry_run.
restore_library_snapshotA
STRICTLY ADDITIVE restore of a library snapshot written by backup_library (see list_backups). Adds only what is missing: saves absent tracks/albums/shows/episodes/audiobooks, follows unfollowed artists, and creates NEW playlists named 'Restored · ()' — existing playlists are never touched and nothing is deleted, renamed, or overwritten. Truncated snapshots are previewable but refused before confirmation or writes; quota-hit, contentless or wrong-schema_version snapshots are refused outright. Prompt and result state where the stored data came from, the date the FILE declares (naming the reason when absent — never the mtime), the item count, and the single use made of it; dry_run defaults to TRUE (read-only preview); setting dry_run=false requires explicit confirmation before any write, fails closed when elicitation is unavailable or errors, and allows writes when SPOTIFY_MCP_CONFIRM=never.
Inputs: backup_path (required), dry_run, categories, max_results, +1 more.
save_discover_weeklyA
Archive your Discover Weekly into a regular playlist (creates or overwrites the archive). Resolves Discover Weekly via /me/playlists exact match first, falling back to search (unverified); dry_run previews; idempotent if archive already matches. Result echoes source identity (owner, url, verified).
Inputs: dry_run, archive_name, response_format.
save_release_radarA
Archive your Release Radar into a regular playlist (creates or overwrites the archive). Resolves Release Radar via /me/playlists exact match first, falling back to search (unverified); dry_run previews; idempotent if archive already matches. Result echoes source identity (owner, url, verified).
Inputs: dry_run, archive_name, response_format.
save_sceneA
Save a named playback scene (device + volume + shuffle/repeat + optional context) to the local sidecar (~/.spotify-mcp/scenes.json)
Inputs: name (required), repeat, volume, shuffle, +3 more.
save_to_libraryA
Preferred. Accepts the widest URI mix (track, album, episode, show, audiobook, user, playlist) in one request. Save one or more items to the user's library via Spotify's unified library endpoint. Max 40. PREVIEWS BY DEFAULT — pass dry_run=false to commit.
Inputs: uris (required), dry_run, response_format.
schedule_wind_downA
Preview or start a volume wind-down: absolute-minute volume steps, then pause. Set dry_run to preview without replacing or cancelling an active timer.
Inputs: minutes (required), dry_run, device_id, floor_volume, +2 more.
searchARead-onlyIdempotent
Search Spotify's catalog for tracks, artists, albums, playlists, shows, episodes, or audiobooks. Pass types as an array (e.g. ["artist"]) to search a single kind — no track/album fallback noise. Decision guide: search (general, ≤10/type), search_deep (paginated fetch_all up to 50/type), search_fresh (tag:new last 2 weeks), search_by_isrc (exact ISRC), whats_new (personal radar from follows).
Inputs: query (required), limit, types, market, +4 more.
search_deepARead-onlyIdempotent
Paged catalog search that walks past the API limit of 10 results per type. Fetches up to 5 pages of 10 results per requested type server-side from a caller-supplied offset, dedupes by id, and returns compact rows. Type walks overlap (width: SPOTIFY_MCP_MAX_CONCURRENCY, else SPOTIFY_MCP_FANOUT_CONCURRENCY, else 4); same request count. Decision guide: use search_deep when you need >10 results/type or a later window; otherwise use search (single page), search_fresh (new releases), search_by_isrc (ISRC-exact), whats_new (personal follows).
Inputs: query (required), pages, types, market, +3 more.
search_history_statsBRead-onlyIdempotent
Analytics over the local search-history sidecar: top queries, type breakdown, recency. Quota: local only (no API).
Inputs: top_n, response_format.
search_saved_albumsARead-onlyIdempotent
Search saved albums (client-side filter over bounded walk). Quota: GET /me/albums paged.
Inputs: query, artist, scan_cap, added_after, +2 more.
search_saved_audiobooksARead-onlyIdempotent
Search saved audiobooks (bounded walk + client-side filter). Quota: GET /me/audiobooks paged.
Inputs: query, scan_cap, max_results, response_format.
search_saved_episodesBRead-onlyIdempotent
Search saved episodes (bounded walk + client-side filter). Quota: GET /me/episodes paged.
Inputs: show, query, scan_cap, max_results, +1 more.
search_saved_showsARead-onlyIdempotent
Search saved podcast shows (bounded walk + client-side filter). Quota: GET /me/shows paged.
Inputs: query, scan_cap, max_results, response_format.
search_saved_tracksARead-onlyIdempotent
Search your Liked Songs (saved tracks) by text query and optional facets — client-side filter over a bounded walk of /me/tracks. For catalog-wide search use search. Reports walk truncation.
Inputs: album, limit, query, artist, +6 more.
search_within_playlistARead-onlyIdempotent
Text search inside a single playlist: a client-side filter over the rows the walk read, cheaper than paging get_playlist_items yourself for a narrow query — but it can only see that window, so scanned_items/scan_cap/scan_truncated say how much of the playlist was actually read. Matches item name, artist, album and show name; kind narrows a mixed playlist to tracks only or episodes only. Quota: GET /playlists/{id}/items paged.
Inputs: query (required), id, kind, market, +3 more.
seekB
Seek to a position in the current track
Inputs: position_ms (required), dry_run, device_id, response_format.
set_repeatB
Set repeat mode: off, context (repeat playlist/album), or track (repeat single track)
Inputs: state (required), dry_run, device_id, response_format.
set_shuffleC
Enable or disable shuffle mode
Inputs: state (required), dry_run, device_id, response_format.
set_volumeA
Set playback volume on one device, on a selection of devices, or across every live device. volume_percent sets an absolute level; delta_step nudges the current level by a signed step. op picks the variant: "mute" drops to 0 and remembers the level, "unmute" restores what mute remembered, "preset" applies the per-device presets stored by set_device_volume_preset, and "level" with no volume_percent copies the active device's level to the others. Quota: 1 write for a single device; 1 read + N writes when fanning out.
Inputs: op, dry_run, device_id, delta_step, +5 more.
show_new_episodesARead-onlyIdempotent
Find new episodes across your saved podcast shows: reports episodes released within the lookback window (default 7 days), marking which are already saved in your episode library. Fetches /me/shows then each show's latest episodes, overlapping episode lookups (width: SPOTIFY_MCP_MAX_CONCURRENCY, else SPOTIFY_MCP_FANOUT_CONCURRENCY, else 4) so a 25-show scan is not 25 serial round trips. WARNING: M saved shows → M+1 requests (1 show page + M episode lookups). Use max_shows to budget and cost_preview to see the cost without making any calls. This tool is read-only: nothing is ever changed.
Inputs: days, market, max_shows, max_results, +3 more.
skip_nextB
Skip to the next track in the queue or context.
Inputs: dry_run, device_id, response_format.
skip_previousA
Skip to the previous track. If more than 3 seconds in, restarts the current track first.
Inputs: dry_run, device_id, response_format.
split_playlistB
Split a playlist into N chunks (new playlists). Quota: GET all + N POST /me/playlists + N POST items.
Inputs: parts (required), playlist_id (required), public, dry_run, +1 more.
spotify_doctorARead-onlyIdempotent
Run read-only diagnostics: token presence/expiry, auth-time scopes vs write tools enabled by active toolsets, Premium gating, rate-limit cooldown, config state, visible account details when reachable, and the live registered-tool surface with toolset/scope/READONLY trim causes. The only live request is GET /me; no mutation requests are issued.
Inputs: verbose, response_format. Returns: object
start_podcast_sessionA
Plan a podcast session (see plan_podcast_session) and start it on a device. Limitation: Spotify cannot apply resume offsets when queueing — only the first episode can start at its resume point (via PUT /me/player/play on its show context); later episodes are appended to the queue and play from the beginning. With dry_run, nothing is played or queued.
Inputs: minutes (required), kind, market, dry_run, +4 more.
switch_accountADestructive
Change which registered account this session acts as. Takes effect for every subsequent call in this session: the client re-points its token file, drops the previous account's cached reads and validators, and refuses to switch while a request is in flight. Asks for confirmation first, because every later write then lands in the new account's library. Changes local session state and the account registry only — it issues no Spotify writes.
Inputs: profile (required), response_format.
tag_managementA
Declare or retract genre tags for an artist in your local sidecar (~/.spotify-mcp/genre-tags.json), which library_genre_report and filter_by_genre consume. add requires at least one tag; remove drops the listed tags, or the artist entirely when none are listed. Supports dry_run preview.
Inputs: action (required), artist (required), tags, dry_run, +1 more.
toolset_reportA
Report the active toolsets and registration modules, plus the live registered tool count — answers "how much surface is exposed right now". Discovery set; always available. Also see find_tool / inspect_tool.
Inputs: response_format. Returns: object
transfer_playbackA
Move playback to a different Spotify Connect device, named by exact id, by the label you gave it, or by a case-insensitive name substring. A plain transfer restarts the track at 0:00 on the target; preserve_position: true carries the current track and play position across instead, and restore_shuffle_repeat: true re-applies the current shuffle and repeat modes on the target. Quota: 1 read to resolve the device, then 1–4 writes depending on the flags.
Inputs: device (required), play, volume, dry_run, +4 more.
undo_last_mutationADestructive
Undo the most recent reversible mutation (receipt FIFO). Same inversion semantics as undo_mutation: add/save → remove, removal → re-add. Executing needs confirmation and is refused when the client cannot prompt (SPOTIFY_MCP_CONFIRM=never bypasses).
Inputs: dry_run, response_format.
undo_mutationADestructive
Undo a specific mutation by receipt ID. Inverts the recorded direction: an add/save is undone by removing, a removal by re-adding (playlist items or library). A playlist add undo removes only the rows it created, refusing when no row positions are recorded. The result reflects the refetched post-state. Non-reversible kinds return not reversible. Executing needs confirmation and is refused when the client cannot prompt (SPOTIFY_MCP_CONFIRM=never bypasses).
Inputs: receipt_id (required), dry_run, response_format.
unfollow_playlistADestructive
Unfollow a playlist — remove it from your Spotify library — via DELETE /me/library. Always asks before writing unless SPOTIFY_MCP_CONFIRM=never.
Inputs: playlist_id (required), dry_run, response_format. Returns: ok, dry_run, receipt, cancelled
unpin_playlistADestructive
DEPRECATED, use unfollow_playlist. This tool never unpinned anything; it has always removed the playlist from your Spotify library via DELETE /me/library.
Inputs: playlist_id (required), dry_run, response_format. Returns: ok, dry_run, receipt, cancelled
unsave_orphan_tracksADestructive
Find saved tracks that appear in no playlist (orphans) and optionally unsave them. Quota: walks library + all playlists (capped). PREVIEWS BY DEFAULT — pass dry_run=false to commit. Removing 10+ orphans additionally requires elicitation confirmation (or SPOTIFY_MCP_CONFIRM=never for automation).
Inputs: dry_run, scan_cap, max_remove, response_format.
update_playlistC
Update a playlist's name, description, or visibility
Inputs: id, name, public, dry_run, +3 more.
upload_playlist_coverA
Replace a playlist's cover image with a base64-encoded JPEG. Requires the ugc-image-upload scope on the Spotify developer dashboard app (plus playlist-modify-public/private); without it Spotify rejects the upload with 403.
Inputs: jpeg_base64 (required), playlist_id (required), dry_run.
verify_receiptARead-onlyIdempotent
Verify that a previous mutation actually landed on Spotify by looking up its receipt. Receipts are session-scoped: the 100 most recent mutations, in this process only, and lost on restart unless SPOTIFY_MCP_RECEIPTS is set. An unknown or expired id returns isError with found:false — a fact about the lookup, not about the mutation.
Inputs: receipt_id (required).
whats_newA
Personal new-releases radar: derive what's new from followed artists (new albums/singles) and saved shows (new podcast episodes), replacing the removed browse/new-releases surface. WARNING: the follow list is paged 50 artists per request, so on a COLD read cache the album leg costs ceil(max_artists/50) follow pages PLUS up to max_artists album lookups (#679); a repeat scan inside the cache window re-probes the same canonical request and spends no request (#900). A large library can still exhaust small dev-account quotas in one call. Use max_artists to budget and dry_run to preview the cost before running; dry_run labels its figure a budget bound (it is arithmetic over the budget, not a measurement) and a real call reports the request count it actually issued in cost. Decision guide: whats_new for personal follows radar; search_fresh for query-scoped tag:new, search/search_deep for general catalog, search_by_isrc for ISRC-exact.
Inputs: kinds, since, dry_run, days_back, +3 more.
wind_down_statusA
Read the current or most recent wind-down progress, including per-step failures
Inputs: device_id, response_format.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 131 tools
Many tools have genuinely distinct purposes and the descriptions include explicit decision guides (search vs search_deep vs search_fresh vs search_by_isrc vs whats_new; get_now_playing vs get_currently_playing), which helps a lot. However, there are several near-duplicate clusters (pin_playlist/follow_playlist, unpin_playlist/unfollow_playlist, multiple duplicate-detection tools, add_to_playlist/batch_add_to_playlist/merge_playlists/copy_playlist/move_items_between_playlists) that create real selection ambiguity. Boundaries are only disentangled by reading long prose, not by name.
The overwhelming majority of tools follow a snake_case verb_noun pattern (get_saved_tracks, create_playlist, add_to_playlist, remove_from_library, export_library_json). A handful deviate (whats_new, spotify_doctor, call_tool, play_from_search, schedule_wind_down), but these are readable and mostly intentional, so the convention is only mildly broken.
131 tools is an extreme surface far beyond what any agent can hold in context, and the server itself acknowledges this with dispatcher tools (find_tool, inspect_tool, call_tool, enable_toolset) built to work around its own size. The mass includes deprecated shims and many rarely-needed one-off utilities. This is a textbook over-scoped surface.
Coverage of the Spotify domain is remarkably thorough: playback, queue, devices, playlists (full CRUD plus transform ops), library CRUD, search variants, exports, backups, restore, undo, and diagnostics are all present, with no obvious core lifecycle gaps. The main shortfalls are deprecated/unavailable operations (get_user_profile, get_user_playlists_by_id, artist follow) that are documented as dead rather than removed, plus the sheer redundancy diluting the surface.
Maintenance
Related MCP Connectors
Spotify: Spotify Data API for Millions of songs & podcasts, artists, albums, playlists and more.
Full Spotify Web API coverage - albums, artists, playlists, player controls, and more.
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
Create songs from prompts or lyrics, check credits, and access your private library with OAuth.
Related MCP Servers
- FlicenseBqualityDmaintenanceEnables AI assistants to control Spotify playback, search for music, manage playlists, and interact with your Spotify library through natural language commands.19-
- FlicenseAqualityDmaintenanceEnables AI assistants to control Spotify playback, search for music, manage playlists, and access library information through the Spotify API. Requires Spotify Premium for playback control features.4-
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to control Spotify playback, search music, manage playlists and library, and access user listening insights via the Spotify Web API.-
- FlicenseBqualityCmaintenanceEnables AI assistants to control Spotify playback, search the catalog, and manage playlists and liked songs through natural language. Supports reading currently playing tracks, queues and devices, plus play, pause, skip, queueing, volume control, and playlist creation and editing.30-