<p align="center">
  <img src="https://upload.wikimedia.org/wikipedia/commons/8/84/Spotify_icon.svg" width="72" height="72" alt="Spotify logo">
</p>

<h1 align="center">Spotify MCP Server</h1>

<p align="center">
  Let AI assistants control Spotify, build playlists, and plan DJ sets from BPM, key, and energy data.
</p>

<p align="center">
  <a href="plugins/spotify-controller/README.md"><strong>Install with Codex</strong></a>
  ·
  <a href="docs/setup.md">Set up another MCP client</a>
  ·
  <a href="docs/tools.md">Explore the tools</a>
</p>

Works with Codex, Cursor, Claude, Cline, and other MCP clients. The repository also ships the agent skills that guide setup, playlist curation, and DJ set planning.

> Started from [marcelmarais/spotify-mcp-server](https://github.com/marcelmarais/spotify-mcp-server) and since rewritten from scratch. Follow [this repository's setup](docs/setup.md), not upstream's. [MIT licensed](LICENSE).

## Start here

### Codex

Install the plugin with two commands:

```bash
codex plugin marketplace add martin-gomola/spotify-mcp-server --ref main
codex plugin add spotify-controller@spotify-mcp-server
```

Then tell Codex:

> Set up Spotify for me. Do the technical parts yourself and tell me only what you need from my Spotify account.

The setup skill handles the local install and authentication, asking only for the Client ID and Client Secret from your Spotify app. See the [Spotify Controller guide](plugins/spotify-controller/README.md) for the two-minute walkthrough.

### Other MCP clients

You need Node.js 18+, a Spotify Premium account, and a Spotify Developer app with `http://127.0.0.1:8888/callback` registered as a Redirect URI. Spotify's current Development Mode requires the app owner to have Premium; playback also needs Spotify open on an available device.

```bash
git clone https://github.com/martin-gomola/spotify-mcp-server.git
cd spotify-mcp-server
npm install && npm run build
cp spotify-config.example.json spotify-config.json  # add your client ID and secret
npm run auth
```

Then point your client at `build/index.js`. The [setup guide](docs/setup.md) has configuration for Claude Desktop, Cline, and Cursor. BPM and key need nothing extra: they come from ReccoBeats, which takes no key.

## Try asking

- _"Play Elvis's first song"_
- _"Create a Taylor Swift / Slipknot fusion playlist"_
- _"Copy the techno tracks from my workout playlist into my work playlist"_
- _"Reorder my house playlist into a set that warms up, peaks, then cools down"_
- _"What's the BPM and key of everything in this playlist?"_

## What it does

The server covers playback control, search, playlist and album editing, and listening history through a focused MCP toolset. See the [core tool reference](docs/tools.md); audio analysis and DJ tools are documented separately under [DJ sets](docs/dj-sets.md).

Its DJ workflow goes further:

1. `analyzeDjPlaylist` reads BPM, Camelot key, and playlist-relative energy, naming the source behind every value.
2. `planDjSet` creates a reviewable set order with harmonic mixing, a shaped energy curve, artist spacing, and anchors you pin by hand.
3. `applyDjSetPlan` writes the approved order. It defaults to a dry run, checks the playlist snapshot before and after, and keeps a receipt so a half-applied reorder rolls back.

See [DJ sets](docs/dj-sets.md) for the full analyze, plan, apply, and restore flow.

## Documentation

| Guide | Covers |
| --- | --- |
| [Setup](docs/setup.md) | Spotify app, credentials, OAuth, connecting a client |
| [Tools](docs/tools.md) | Read, playback, playlist, and album tools with parameters |
| [DJ sets](docs/dj-sets.md) | Where BPM and key come from, the analyze/plan/apply flow, set shaping, restore |
| [Agent skills](docs/agent-skills.md) | The bundled skills and how to use them outside this repo |
| [Codex plugin](docs/codex-plugin.md) | Shipping the server and skills as a plugin that tracks `main` |
| [Development](docs/development.md) | Scripts, layout, the Spotify API rules, local data |