Skip to main content
Glama

SpotifyMCP

CI npm version License: MIT Node

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.

→ Read the 3.0 roadmap


🤖 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

dry_run previews on writes, receipts that prove what landed, human confirmation for bulk deletes, and READONLY to hide write-capable modules.

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 SPOTIFY_MCP_EXPERIMENTAL_ANALYTICS=1, because Spotify's Developer Policy Sec. III.13 prohibits building derived listenership metrics. The rest of the analytics surface, which re-presents your own data, is always on. See docs/compliance.md.

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 src/gating.ts.

Polished

Paginated (up to 500), podcasts first-class, device-aware playback, spotify_doctor self-diagnosis, real test suite.

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/callback

Copy the Client ID.

2. Authenticate

SPOTIFY_CLIENT_ID=your_client_id_here npx -y @novalux12/spotify-mcp@latest auth

Opens 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 auth

Windows (PowerShell):

$env:SPOTIFY_CLIENT_ID="your_client_id_here"; npx -y @novalux12/spotify-mcp@latest auth

Windows 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 back

Check: 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_here

OpenClaw — ~/.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

SPOTIFY_MCP_TOOLSETS

unset

Trim by group for hosts that cap tool counts. Unset registers the curated default surface; all registers everything. The tool count for each is in the generated census above.

SPOTIFY_MCP_STATSFM

1

Register the 50 stats.fm-backed tools across four registration keys — statsfm, taste, tastecomposites and tastejukebox. Off by default: they need a separate stats.fm username. Two of them write to Spotify (taste_to_playlist and statsfm_jukebox); the rest are read-only. spotify-mcp tools counts what your environment actually registers.

SPOTIFY_MCP_READONLY

1

Hide write-capable modules; read-only resources and prompts remain available.

SPOTIFY_MCP_HISTORY

1

Log mutations to JSONL for undo and audit.

SPOTIFY_MCP_RECEIPTS

1

Persist mutation receipts so verify_receipt/undo_mutation survive a restart.

SPOTIFY_MCP_ATTRIBUTION

0

Turn off the "Music data supplied by Spotify" footer and the per-row open.spotify.com link. On unless set to 0/false/no/off; the disclosure is mandatory, so only an explicit falsy value removes it.

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:

  1. get_show_episodes is removed. Use list_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.

  2. Destructive writes fail closed. Any confirmation-gated bulk write now refuses when the client cannot elicit, instead of proceeding unprompted. archive_played_episodes's confirm: true no longer authorises the delete (it is still accepted, and every result says it was ignored). For headless automation, set SPOTIFY_MCP_CONFIRM=never deliberately.

  3. Playlist set-operation inputs are canonical. A/B pairs are playlist_a/playlist_b; ordered lists are playlists; playlist_subtract takes the base as base_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 a validation error whose reason is retired_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_b

    a/b, or playlist_id_a/playlist_id_b, or playlist_a_id/playlist_b_id — one of them, per tool

    ordered list

    playlists

    playlist_ids, or source_playlist_ids, or sources — one of them, per tool

    subtraction

    base_playlist_id + playlists

    subtract_playlist_ids, or the positional form playlists: [base, ...sources] — one of them, per tool

    base_playlist_id is 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 an unknown_param error — a different claim from retired_input, which says the server published that name until 3.0.

  4. Numeric caps have canonical names. max_results caps what is returned; limit and scan_cap cap how much of each source is read.

  5. Unknown arguments are rejected with a typed unknown_param error 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

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 200 is 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: true rather than deleting them — /artists/{id}/top-tracks and all seven Get Several batch 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 answers 200 is unverified (#1338): no probe in this repository shows it, and the one probe artefact that was once cited for it records 403 on 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

browse-categories — /browse/categories* (list, {id}, {id}/playlists)

get_category, browse_category_deepdive, category_resolver

403 explained

browse-new-releases — /browse/new-releases

(none — no shipped tool reads this path)

Replaced; no call site

markets — /markets

get_available_markets, market_validate

403 explained

artist-top-tracks — /artists/{id}/top-tracks

get_artist_top_tracks, queue_playlist, artist_collab_network, artist_completeness_score, batch_add_to_playlist, copy_playlist, move_items_between_playlists

403 explained

user-profile — /users/{id} and /users/{id}/playlists

get_user_profile, get_user_playlists_by_id, get_playlist_followers

403 explained

me-type-contains — the documented /me/{type}/contains checks (tracks, albums, shows, episodes, audiobooks, following)

(none — migrated to GET /me/library/contains)

Replaced; no call site

playlist-followers-contains — /playlists/{id}/followers/contains

(none — migrated to GET /me/library/contains)

Replaced; no call site

batch-several — the multi-id ?ids= batch endpoints (/tracks, /albums, /artists, /episodes, /shows, /audiobooks, /chapters)

get_several_tracks, get_several_albums, get_several_artists, get_several_episodes, get_several_shows, get_several_audiobooks, get_several_chapters, catalog_batch_lookup

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 row

Notes:

  • 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/contains is not gated (it returned 200 on the same probe) and backs the saved-state reads behind check_playlist_following, restore_library_snapshot and receipt verification. The contains families 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 Several batch endpoint answers 403, fetchSeveral retries through per-id GET /<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 carries degraded: true and a [degraded: batch endpoint returned 403; … fetched individually] footer in prose, plus degraded_reason in structuredContent, 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-analysis and /browse/featured-playlists reads, and the /playlists/{id}/tracks family (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.json exists 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_URI to another port, or use SPOTIFY_HEADLESS=1. The message names EADDRINUSE and the port because the usual cause is a previous auth still 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.

  • Forbidden on lookup tools (categories, markets, top-tracks, user profiles, the per-type contains checks) → these endpoints are registration-gated by Spotify; see Registration-gated endpoints. (GET /me/library/contains is not one of them, so a 403 there is a real problem, not a gated registration.)

  • Still stuck? npx -y @novalux12/spotify-mcp@latest doctor or 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 tests

Not affiliated with Spotify. Use per the Spotify Developer Terms.

MIT © Carme99 and NovaLux12 contributors · Acknowledges calebWei/SpotifyMCP and varunneal/spotify-mcp.

Available Tools

131 tools
add_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_libraryA
Read-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_toolA
Destructive

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_artistsA
Read-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_libraryA
Read-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_followingA
Read-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_playlistsA
Destructive

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_artifactsA
Destructive

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_coversA
Read-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_backupA
Destructive

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_sceneA
Destructive

Delete a saved playback scene from the local sidecar

Inputs: name (required), response_format.

diff_playlistsA
Read-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_genreA
Read-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_tracksA
Read-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_playlistA
Read-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_playlistsA
Read-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_toolA
Read-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_playingA
Read-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_devicesA
Read-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_artistsA
Read-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_playingA
Read-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_playlistA
Read-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_datesB
Read-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_coverB
Read-onlyIdempotent

Get a playlist's cover image URLs

Inputs: id, max_results, playlist_id, response_format.

get_playlist_itemsA
Read-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_snapshotA
Read-onlyIdempotent

Expose snapshot_id + item count for optimistic concurrency. Quota: 2 GETs.

Inputs: playlist_id (required), max_results, response_format.

get_queueA
Read-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_albumsA
Read-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_countsA
Read-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_episodesA
Read-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_showsA
Read-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_tracksA
Read-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_playlistsB
Read-onlyIdempotent

List the current user's playlists

Inputs: limit, offset, fetch_all, max_results, +1 more.

get_user_playlists_by_idA
Read-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_profileA
Read-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.

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_toolA
Read-onlyIdempotent

Show one tool's full description and input schema before calling it

Inputs: tool_name (required), response_format. Returns: object

library_genre_reportA
Read-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_accountsA
Read-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_backupsB
Read-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_scenesB
Read-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_sessionA
Read-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.

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

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_libraryA
Destructive

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_playlistA
Destructive

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_playlistB
Destructive

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

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.

search_deepA
Read-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_statsB
Read-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_albumsA
Read-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_audiobooksA
Read-onlyIdempotent

Search saved audiobooks (bounded walk + client-side filter). Quota: GET /me/audiobooks paged.

Inputs: query, scan_cap, max_results, response_format.

search_saved_episodesB
Read-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_showsA
Read-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_tracksA
Read-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_playlistA
Read-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_episodesA
Read-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_doctorA
Read-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_accountA
Destructive

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_mutationA
Destructive

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_mutationA
Destructive

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_playlistA
Destructive

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_playlistA
Destructive

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_tracksA
Destructive

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_receiptA
Read-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

    B3.4/5.0

    Scored across 131 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count1/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Enables 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
      -
    • F
      license
      B
      quality
      C
      maintenance
      Enables 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
      -