79 lines
2.5 KiB
Markdown
79 lines
2.5 KiB
Markdown
|
# 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:
|
||
|
|
|
||
|
|
```
|
||
|
|
SPOTIFY_CLIENT_ID=your_client_id_here
|
||
|
|
SPOTIFY_CLIENT_SECRET=your_client_secret_here
|
||
|
|
```
|
||
|
|
|
||
|
|
### 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"]
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
````
|
||
|
|
|
||
|
|
**Note:** 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:...`). |
|