# spotify-mcp

An MCP (Model Context Protocol) server for Spotify. Control playback, search for music, manage playlists, and get personalized recommendations -- all through any MCP-compatible client like Claude.

## Tools

| Tool | Description |
|------|-------------|
| `auth-spotify` | Authenticate with Spotify via OAuth |
| `search-spotify` | Search for tracks, albums, artists, or playlists |
| `get-current-playback` | Get the current playback state (track, device, progress) |
| `play-track` | Play a specific track on an active device |
| `pause-playback` | Pause playback |
| `next-track` | Skip to the next track |
| `previous-track` | Skip to the previous track |
| `get-user-playlists` | List the user's playlists |
| `create-playlist` | Create a new playlist |
| `add-tracks-to-playlist` | Add tracks to a playlist |
| `get-playlist-tracks` | Get the tracks in a playlist |
| `rename-playlist` | Rename a playlist (and optionally update description/visibility) |
| `unfollow-playlist` | Unfollow (or delete) a playlist |
| `get-recommendations` | Get track recommendations based on seed tracks, artists, or genres |
| `get-top-tracks` | Get the user's top played tracks over a time range |

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `SPOTIFY_CLIENT_ID` | Yes | Spotify app client ID |
| `SPOTIFY_CLIENT_SECRET` | Yes | Spotify app client secret |
| `SPOTIFY_REDIRECT_URI` | No | OAuth redirect URI (defaults to `http://127.0.0.1:8888/callback`) |

Create a Spotify app at [developer.spotify.com](https://developer.spotify.com/dashboard) and add your redirect URI to the app's settings.

## Setup

```bash
npm ci
```

## Usage

### Stdio mode (for MCP clients that launch the server directly)

```bash
node build/index.js
```

### HTTP mode (using mcp-proxy)

```bash
mcp-proxy --port 8002 -- node build/index.js
```

### Authentication

On first use, call the `auth-spotify` tool. It will open a browser window for Spotify OAuth. Tokens are persisted to `~/.spotify-mcp/tokens.json` so you only need to authenticate once.

## License

MIT