spotify-mcp

A remote MCP (Model Context Protocol) server for Spotify, running on Cloudflare Workers. It lets an AI assistant search Spotify and manage your playlists, library and playback — including moving tracks around inside playlists.

Auth is handled entirely over the web: the server is its own OAuth provider to the MCP client, and performs the Spotify OAuth flow upstream. There is no local binary and no authenticate tool — connecting the server in your MCP client opens the Spotify consent screen in your browser.

Architecture

• McpAgent (SpotifyMCP, a Durable Object) hosts the MCP server and tools, served over Streamable HTTP at /mcp (and legacy SSE at /sse).
• @cloudflare/workers-oauth-provider wraps the Worker. It issues tokens to MCP clients and stores the upstream Spotify tokens (access + refresh) encrypted in the grant props.
• SpotifyHandler (Hono app) implements /authorize and /callback, driving the Spotify authorization-code flow and showing the consent dialog.
• The agent persists a working access token in its Durable Object state and refreshes it automatically using the stored refresh token.

MCP client ──/mcp──▶ OAuthProvider ──▶ SpotifyMCP (Durable Object)
     │                    │                     │
   /authorize        /callback            Spotify Web API
     └────── Spotify consent (browser) ────────┘

Tools

Tool	What it does
get_me	Current user profile
search	Search tracks / albums / artists / playlists
list_playlists	Your playlists
get_playlist_tracks	Playlist details + tracks with their positions
create_playlist	Create a playlist
update_playlist_details	Rename / re-describe / change public state
add_tracks_to_playlist	Add tracks, optionally at a specific position
remove_tracks_from_playlist	Remove tracks
reorder_playlist_tracks	Move a track (or range of tracks) to a new position
unfollow_playlist	Unfollow / delete a playlist
get_saved_tracks / save_tracks / remove_saved_tracks	Liked-songs library
get_playback_state	What's playing, on which device
control_playback	play / pause / next / previous (Premium + active device)
add_to_queue	Queue a track

Deploy it yourself

Runs on the Cloudflare Workers free tier.

Prerequisites

• A Cloudflare account and the Wrangler CLI logged in (npx wrangler login).
• A Spotify Developer account.
• Node.js 18+.

0. Get the code

git clone https://github.com/lassejlv/spotify-mcp.git
cd spotify-mcp
npm install --ignore-scripts   # --ignore-scripts avoids an unused native build (sharp)

1. Create a Spotify app

At https://developer.spotify.com/dashboard, create an app and note the Client ID and Client Secret. Under Redirect URIs, add your Worker's callback URL:

https://spotify-mcp.<your-subdomain>.workers.dev/callback

(The workers.dev subdomain is shown after the first wrangler deploy. Add the URI, then deploy again if needed. A custom domain's /callback works too.)

2. Create the KV namespace

The OAuth provider stores grants, tokens and clients in KV.

npx wrangler kv namespace create OAUTH_KV

Copy the returned id into wrangler.jsonc, replacing the existing OAUTH_KV id value (the checked-in one belongs to the original author's account and won't work for you).

3. Set secrets

npx wrangler secret put SPOTIFY_CLIENT_ID       # your Spotify Client ID
npx wrangler secret put SPOTIFY_CLIENT_SECRET   # your Spotify Client Secret
npx wrangler secret put COOKIE_ENCRYPTION_KEY   # any random string, e.g. `openssl rand -hex 32`

Optional — restrict who can use the server:

# Comma-separated allowlist of Spotify account emails. Only these accounts can
# authorize; everyone else is rejected at the callback (no token issued).
# Leave unset to allow any Spotify account.
npx wrangler secret put ALLOWED_EMAILS          # e.g. me@example.com,friend@example.com

4. Deploy

npx wrangler deploy

Your server is now live at https://spotify-mcp.<your-subdomain>.workers.dev/mcp.

Connect an MCP client

Point any remote-MCP-capable client at the /mcp URL. Clients that only speak stdio can bridge via mcp-remote:

{
  "mcpServers": {
    "spotify": {
      "command": "npx",
      "args": ["mcp-remote", "https://spotify-mcp.<your-subdomain>.workers.dev/mcp"]
    }
  }
}

On first connect, your browser opens: approve the MCP client, then log in and grant Spotify access. Tokens are refreshed automatically thereafter.

Local development

cp .dev.vars.example .dev.vars   # then fill in the three values
npx wrangler dev

wrangler dev simulates KV locally. Use http://localhost:8788/callback as an additional Spotify redirect URI for local testing.

Notes

• Tracks and playlists can be referenced by bare ID or full spotify: URI in any tool.
• reorder_playlist_tracks uses zero-based positions; call get_playlist_tracks first to see current positions.
• Playback control endpoints require Spotify Premium and an active device.
• Requested scopes: playlist read/modify (public + private), library read/modify, playback read/modify, user-read-private, and user-read-email (used for the ALLOWED_EMAILS access gate).
• Access control: set the ALLOWED_EMAILS secret to a comma-separated list to restrict the server to specific Spotify accounts; leave it unset to allow anyone.