# spotify-mcp

A **remote** MCP (Model Context Protocol) server for Spotify, running on
[Cloudflare Workers](https://developers.cloudflare.com/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](https://dash.cloudflare.com/sign-up) and the Wrangler CLI logged in (`npx wrangler login`).
- A [Spotify Developer](https://developer.spotify.com/dashboard) account.
- Node.js 18+.

### 0. Get the code

```sh
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.

```sh
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

```sh
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:

```sh
# 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

```sh
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`](https://www.npmjs.com/package/mcp-remote):

```json
{
  "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

```sh
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.