# Spotify MCP

Model Context Protocol (MCP) server for **Spotify**. Let AI agents like Cursor, Claude Code, and Codex search tracks and control playback through the Spotify Web API.

## Features

- Search tracks by title, artist, or natural language
- Play, pause, resume, skip, and go previous
- Search-and-play / search-and-queue in one step
- Read what’s currently playing
- List Spotify Connect devices and transfer playback
- Set volume (0–100%)
- OAuth login with automatic token refresh

## Requirements

- **Node.js 18+**
- A **Spotify Premium** account (playback control requires Premium)
- A Spotify Developer app ([Dashboard](https://developer.spotify.com/dashboard))

## Quick start

### 1. Clone and install

```bash
git clone https://github.com/AndreaZero/spotify-mcp.git
cd spotify-mcp
npm install
```

### 2. Create a Spotify app

1. Open the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard).
2. Create an app.
3. Under **Redirect URIs**, add:

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

4. Copy the **Client ID** and **Client Secret**.

### 3. Configure environment

```bash
cp .env.example .env
```

Edit `.env`:

```env
SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888/callback
```

### 4. Authenticate

```bash
npm run auth
```

Open the printed URL in your browser, approve access, then wait until you see `Spotify authentication successful.` Tokens are saved to `.spotify-token.json` (gitignored) and refreshed automatically.

### 5. Run

```bash
npm start
```

## Cursor setup

Add the server to your MCP config (e.g. `~/.cursor/mcp.json` or project `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "spotify": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "cwd": "/absolute/path/to/spotify-mcp",
      "env": {
        "SPOTIFY_CLIENT_ID": "your_spotify_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_spotify_client_secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8888/callback"
      }
    }
  }
}
```

On Windows, use a full path for `cwd`, for example:

```text
C:\\Users\\you\\Documents\\cursor-projects\\spotify-mcp
```

You can omit `env` if credentials already live in the project `.env` and the process starts with that working directory.

After saving, restart Cursor (or reload MCP servers), then try:

> Play Everlong by Foo Fighters

> What’s playing right now?

> Set volume to 30

## Claude Desktop / other MCP clients

Same idea: run `npx tsx src/index.ts` with `cwd` set to this repo and the Spotify env vars available.

## Tools

| Tool | Description |
|------|-------------|
| `spotify_search_track` | Search tracks (`query`, optional `limit` 1–10) |
| `spotify_play` | Play a track URI on the active (or given) device |
| `spotify_play_search` | Search and play the best match |
| `spotify_pause` | Pause playback |
| `spotify_resume` | Resume playback |
| `spotify_next` | Skip to next track |
| `spotify_previous` | Go to previous track |
| `spotify_add_to_queue` | Queue a track URI |
| `spotify_queue_search` | Search and queue the best match |
| `spotify_now_playing` | Current track and progress |
| `spotify_devices` | List Spotify Connect devices |
| `spotify_transfer` | Transfer playback to another device |
| `spotify_volume` | Set volume 0–100% |

## Scripts

| Command | Description |
|---------|-------------|
| `npm run auth` | Browser OAuth login; writes `.spotify-token.json` |
| `npm start` | Start the MCP server on stdio |
| `npm run inspect` | Open the [MCP Inspector](https://modelcontextprotocol.io) against this server |
| `npm run typecheck` | Run TypeScript checks |

## Project layout

```text
spotify-mcp/
├── src/
│   ├── index.ts      # MCP server & tools
│   ├── auth.ts       # OAuth authorization flow
│   └── spotify.ts    # Spotify Web API client + token refresh
├── .env.example
├── package.json
└── tsconfig.json
```

## OAuth scopes

The auth flow requests:

- `user-read-playback-state`
- `user-read-currently-playing`
- `user-modify-playback-state`

For a longer walkthrough, see [docs/SETUP.md](docs/SETUP.md).

## Troubleshooting

**“Spotify not authenticated”**  
Run `npm run auth` again from the project root.

**“No active device” / playback errors**  
Open Spotify on a phone, desktop, or web player so a Connect device is available, then call `spotify_devices` or `spotify_transfer`.

**Redirect URI mismatch**  
The URI in the Dashboard must match `SPOTIFY_REDIRECT_URI` exactly (default `http://127.0.0.1:8888/callback`).

**Token expired**  
Refresh is automatic when a refresh token exists. If refresh fails, delete `.spotify-token.json` and run `npm run auth` again.

## Security

- Do not commit `.env` or `.spotify-token.json`.
- Keep your Client Secret private.
- See [SECURITY.md](SECURITY.md) for reporting issues.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

[MIT](LICENSE)