Spotify MCP
Model Context Protocol

Spotify, fluent
in Claude.

An MCP server that lets Claude control playback, search the catalog, and manage playlists — in plain language.

The Python server remains supported. Cloudflare / TypeScript is the canonical development direction for a shared local and hosted core. Its merged updates PR is not a deployment announcement; tool contracts differ.

What it does

Everything Spotify, exposed as clean tools.

A focused set of typed MCP tools — each does one thing well, with structured output Claude can reason about.

Playback control

Play, pause, skip, and steer the queue. Claude drives your active device directly.

Smart search

Find tracks, albums, artists, and playlists with pagination for deep catalog dives.

Playlist management

Create, edit, and curate playlists with batch operations that scale to large collections.

Efficient by design

Intelligent batching minimizes API calls, keeping playlist edits fast and within rate limits.

Type-safe

Built on the MCP Python SDK with full Pydantic validation and MyPy compliance for predictable behavior.

Real-time state

Read live playback status and profile data, plus track, artist, album, podcast and audiobook details on demand.

The toolbox

One tool, one job.

No overloaded action parameters — just focused tools that compose.

Playback & queue
get_playback_stateWhat's playing now, on which device
control_playbackPlay tracks, episodes or a context; pause, skip, seek, volume, shuffle, repeat
list_devicesSee every device you can play on
transfer_playbackMove playback to another device
add_to_queueQueue a track or podcast episode on the active device
get_queueView the current playback queue
get_tracksUp to 50 tracks in one request
get_artistUp to 50 artists in one request; top tracks for a single artist
get_albumUp to 20 albums in one request; track list for a single album
search_musicSearch tracks, albums, artists, or playlists
Library & listening history
get_meYour Spotify profile
get_saved_tracksYour Liked Songs, paginated
save_tracksLike tracks in bulk
remove_saved_tracksUnlike tracks in bulk
check_saved_tracksWhich of up to 50 tracks are already liked
check_saved_albumsWhich of up to 20 albums are already saved
check_following_artistsWhich of up to 50 artists the user follows
get_saved_albumsYour saved albums, paginated
save_albumsSave up to 20 albums
remove_saved_albumsRemove up to 20 saved albums
get_followed_artistsArtists you follow, with cursor pagination
follow_artistsFollow up to 50 artists
unfollow_artistsUnfollow up to 50 artists
get_top_itemsYour top artists or tracks over any time range
get_recently_playedWhat you played lately, with timestamps
Podcasts & audiobooks
get_saved_showsYour saved podcast shows, paginated
save_showsSave up to 50 podcast shows
remove_saved_showsRemove up to 50 saved podcast shows
check_saved_showsWhich of up to 50 shows are already saved
get_show_episodesA show's episodes with your resume points, paginated
get_saved_episodesYour saved podcast episodes, paginated
check_saved_episodesWhich of up to 50 episodes are already saved
save_episodesSave up to 50 podcast episodes
remove_saved_episodesRemove up to 50 saved podcast episodes
get_saved_audiobooksYour saved audiobooks, paginated
check_saved_audiobooksWhich of up to 50 audiobooks are already saved
save_audiobooksSave up to 50 audiobooks
remove_saved_audiobooksRemove up to 50 saved audiobooks
Playlists
create_playlistCreate private playlists by default; explicitly opt into public
get_playlistPlaylist metadata and details
get_playlist_tracksRetrieve tracks with full pagination for large playlists
list_playlistsList all your playlists with pagination
add_tracks_to_playlistAdd up to 100 tracks or episodes in one operation
remove_tracks_from_playlistRemove tracks or episodes from a playlist
update_playlist_detailsUpdate name, description, and privacy
reorder_playlistMove tracks to a new position within a playlist
follow_playlistSave a playlist to your library
unfollow_playlistRemove a playlist from your library
Two minutes to set up

Install with one command.

Published on PyPI — no clone, no local path. Run it with uvx.

terminal
$ claude mcp add spotify \
  -e SPOTIFY_CLIENT_ID=your_client_id \
  -e SPOTIFY_CLIENT_SECRET=your_client_secret \
  -e SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888 \
  -- uvx spotify-mcp-jamiew
$ codex mcp add spotify \
  --env SPOTIFY_CLIENT_ID=your_client_id \
  --env SPOTIFY_CLIENT_SECRET=your_client_secret \
  --env SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888 \
  -- uvx spotify-mcp-jamiew
{
  "mcpServers": {
    "spotify": {
      "command": "uvx",
      "args": ["spotify-mcp-jamiew"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8888"
      }
    }
  }
}
{
  "mcpServers": {
    "spotify": {
      "command": "uvx",
      "args": ["spotify-mcp-jamiew"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8888"
      }
    }
  }
}
{
  "mcpServers": {
    "spotify": {
      "command": "uvx",
      "args": ["spotify-mcp-jamiew"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8888"
      }
    }
  }
}
mcp_servers:
  spotify:
    command: uvx
    args: [spotify-mcp-jamiew]
    env:
      SPOTIFY_CLIENT_ID: your_client_id
      SPOTIFY_CLIENT_SECRET: your_client_secret
      SPOTIFY_REDIRECT_URI: http://127.0.0.1:8888

Add -s user to install across all projects.

Same command everywhere: uvx spotify-mcp-jamiew. Requires a Spotify Premium account and uv >= 0.54.

Another client? Paste this to your agent

Install the spotify-mcp MCP server from https://github.com/jamiew/spotify-mcp — it's on PyPI as spotify-mcp-jamiew, run it with uvx spotify-mcp-jamiew, and set env vars SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET, and SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888.

Before connecting

Supported locally, compatible deliberately.

Python keeps six resources, five prompts and playback confirmation. The sibling's merged updates PR added local PKCE login, output schemas, search offset, snapshot guards, bulk playlist progress and removal confirmation, but matching names are not matching contracts. Read the migration comparison before switching.

New playlists are intentionally private by default. Library writes and membership checks accept 50 items per tool call (albums 20), in upstream chunks of at most 40. Failed writes can leave earlier chunks applied. Artist follow checks need user-follow-read, and following artists or playlists needs user-follow-modify: restart and reauthorize Spotify once for the new scopes, without automatically deleting your auth cache.

The March 9 update postponed endpoint restrictions for existing integrations; Extended Quota Mode is exempt from February's endpoint changes. The March changelog reversed external-ID removal. Access depends on the app, not just the date. The official TypeScript SDK's 1.2.0 playlist code still uses legacy routes; switching SDKs does not remove compatibility work.

The July quota update permits 25 apps but shares one Development Mode quota per developer account. QUOTA_EXCEEDED is not ordinary rate limiting; no daily or 24-hour reset is guaranteed. Development Mode normally permits five allowlisted users with a Premium owner, with older larger allowlists grandfathered. Extended access requires an organization, established entity, launched service and at least 250,000 monthly active users. Never share a local token cache or treat a public URL as unrestricted hosting permission.

AI policy is a separate gate. Spotify Developer Policy III.14 restricts ingesting Spotify Content into AI models, not just training. Metadata-only use is not automatic clearance. Analysis and derived metrics (III.13) and voice-control assistants (III.3) also face restrictions. Seek Spotify clarification or approval before public AI access; this project does not establish permission.

Just ask

What it feels like to use.

Create a chill study playlist

Claude searches for fitting tracks, spins up a new playlist, and batch-adds songs in one smooth flow.

Show me my Liked Songs

Handles large libraries gracefully with pagination — even collections of many thousands of tracks.

Find similar artists to Radiohead

Combines search and artist info to surface related artists and queue up their top tracks.