mcp-spotify/README.md

# mcp-spotify

Python MCP server exposing Spotify library and playlist management as tools for Claude.

## Prerequisites

- **Python 3.11+**
- **Spotify Developer Account** with an app registered at [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
  - Note the Client ID and Client Secret from your app
  - Set the Redirect URI to `http://localhost:8888/callback` in your app settings

## Setup

### Step 1: Install dependencies

```bash
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .
```

### Step 2: Configure credentials

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

Edit `.env` and fill in your Spotify credentials:

```
SPOTIPY_CLIENT_ID=your_client_id_here
SPOTIPY_CLIENT_SECRET=your_client_secret_here
SPOTIPY_REDIRECT_URI=http://localhost:8888/callback
```

### Step 3: Authenticate with Spotify

Run the server once with the `--auth` flag to authenticate with Spotify. This will open a browser window where you authorize the app to access your Spotify account. The access token is cached locally at `.cache` in the project directory for subsequent runs.

```bash
python server.py --auth
```

You should see: `Authentication successful! Token cached.`

### Step 4: Register with Claude Code

Add the MCP server to your Claude Code configuration by editing `~/.claude/settings.json`:

````json
{
  "mcpServers": {
    "spotify": {
      "command": "/absolute/path/to/mcp-spotify/.venv/bin/python",
      "args": ["/absolute/path/to/mcp-spotify/server.py"],
      "env": {
        "SPOTIPY_CLIENT_ID": "your_client_id_here",
        "SPOTIPY_CLIENT_SECRET": "your_client_secret_here",
        "SPOTIPY_REDIRECT_URI": "http://localhost:8888/callback"
      }
    }
  }
}
````

**Note:** Replace the path and fill in the env values with your actual Spotify app credentials. The `env` block is required because Claude Code launches the server as a subprocess from a different working directory where `load_dotenv()` may not find your `.env` file.

Replace `/absolute/path/to/mcp-spotify` with the actual path to your project. To find it, run `pwd` in the project directory:

```bash
cd /path/to/mcp-spotify
pwd
```

Then update the paths in `settings.json` accordingly. On Windows, the python path is `.venv\Scripts\python.exe`.

## Available Tools

| Tool | Description |
|------|-------------|
| `list_playlists` | List the authenticated user's Spotify playlists. |
| `get_playlist_tracks` | Get all tracks in a Spotify playlist with full metadata: name, artists, album, duration, popularity, URI, and added_at. |
| `list_saved_tracks` | Get the user's liked/saved tracks from Spotify. Optional limit parameter (default 50). |
| `search_tracks` | Search Spotify for tracks. Returns track URIs that can be passed to add_tracks_to_playlist. |
| `create_playlist` | Create a new Spotify playlist for the authenticated user. Takes name, optional description, and public flag. |
| `add_tracks_to_playlist` | Add tracks to a Spotify playlist by their URIs (e.g., `spotify:track:...`). |