spotify-mcp-server

# SpotifyMCP

[![CI](https://github.com/NovaLux12/spotify-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/NovaLux12/spotify-mcp-server/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/@novalux12/spotify-mcp)](https://www.npmjs.com/package/@novalux12/spotify-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
![Node](https://img.shields.io/badge/node-%3E%3D22.9-brightgreen)

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](#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](docs/configuration.md#toolsets-and-registration-keys).

<!-- BEGIN:generated surface-census -->
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.
<!-- END:generated surface-census -->

### 🚧 3.0 is landing

**3.0 is the release where the open issue list goes 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 *removes* 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](docs/v3-roadmap.md)**

---

> ### 🤖 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](https://developer.spotify.com/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](docs/compliance.md#derived-listening-analytics-the-policy-and-the-interpretation). |
| **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](#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. |

## Quick start

### 1. Create a Spotify app

[Spotify Developer Dashboard](https://developer.spotify.com/dashboard) → Create app → add this Redirect URI exactly:

```
http://127.0.0.1:8888/callback
```

Copy the **Client ID**.

### 2. Authenticate

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

<details><summary>Windows & headless</summary>

**Windows (Command Prompt):**
```cmd
set SPOTIFY_CLIENT_ID=your_client_id_here && npx -y @novalux12/spotify-mcp@latest auth
```

**Windows (PowerShell):**
```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](docs/platform-support.md) for exactly what is
> and is not verified there, and what the known gaps are.

**Headless / remote host:**
```bash
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.

</details>

### 3. Add to your MCP host

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

<details><summary>Claude Code · OpenClaw · other hosts</summary>

**Claude Code (no JSON editing):**
```bash
claude mcp add spotify -- npx -y @novalux12/spotify-mcp@latest
export SPOTIFY_CLIENT_ID=your_client_id_here
```

**OpenClaw** — `~/.openclaw/openclaw.json` → `mcp.servers`:
```json
"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.

</details>

## 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](docs/configuration.md)

`spotify_doctor` (CLI + in-server tool) diagnoses token state, scope gaps, Premi