Content
# Spotify MCP Server
## Overview
The Spotify MCP Server for Claude Desktop allows you to control Spotify playback and manage playlists directly from Claude Desktop using the Model Context Protocol (MCP). Supported actions include playing songs, pausing/resuming playback, skipping tracks, setting volume, creating playlists, adding songs to playlists, and retrieving playback information.
## Prerequisites
- **Claude Desktop**: Version 0.12.28 or later.
- **Python**: Version 3.13 or later (installed at `C:\Users\anush\AppData\Local\Programs\Python\Python313\python.exe`).
- **Spotify Account**: A Spotify account with an active device (e.g., Spotify desktop or mobile app).
- **Spotify Developer Credentials**:
- Obtain `client_id` and `client_secret` from the Spotify Developer Dashboard.
- Ensure the Spotify app is configured with the redirect URI: `http://127.0.0.1:8080/callback`.
## Installation
1. **Install Python Dependencies**:
- Open Command Prompt and navigate to the extension directory:
```bash
cd C:\Users\anush\AppData\Local\AnthropicClaude\app-0.12.28
```
- Install required Python packages:
```bash
C:\Users\anush\AppData\Local\Programs\Python\Python313\python.exe -m pip install fastapi uvicorn requests
```
2. **Set Up Extension Files**:
- Create the extension directory:
```bash
mkdir C:\Users\anush\AppData\Local\AnthropicClaude\app-0.12.28\extensions\spotify
```
- Place the following files in `C:\Users\anush\AppData\Local\AnthropicClaude\app-0.12.28\extensions\spotify`:
- `main.py`: The main MCP server script (see repository or provided code).
- `auth.py`: Handles Spotify OAuth authentication.
- `spotify_api.py`: Interacts with the Spotify API.
- `utils.py`: Utility functions (e.g., token refresh).
- `token_store.py`: Manages user authentication tokens.
- Create `manifest.json` in the same directory:
```json
{
"name": "Spotify",
"version": "1.0.0",
"description": "Spotify control extension for Claude Desktop",
"mcp_server": "spotify"
}
```
3. **Configure Claude Desktop**:
- Create or edit `C:\Users\anush\AppData\Roaming\Claude\claude_desktop_config.json`:
```json
{
"mcpServers": {
"spotify": {
"command": "C:\\Users\\anush\\AppData\\Local\\Programs\\Python\\Python313\\python.exe",
"args": [
"C:\\Users\\anush\\AppData\\Local\\AnthropicClaude\\app-0.12.28\\main.py",
"--client-id",
"your_client_id_here",
"--client-secret",
"your_client_secret_here"
],
"env": {
"PYTHONPATH": "C:\\Users\\anush\\AppData\\Local\\Programs\\Python\\Python313\\Lib\\site-packages"
}
}
}
}
```
- Replace `your_client_id_here` and `your_client_secret_here` with your Spotify credentials.
- Ensure paths use double backslashes (`\\`) for Windows compatibility.
- Validate JSON syntax at JSONLint.
- Secure the file by restricting access (right-click > Properties > Security > limit to your user account).
## Usage
1. **Start Claude Desktop**:
- Launch Claude Desktop (version 0.12.28).
- Ensure the Spotify extension is loaded (check for a slider icon in the input box’s bottom left corner).
- Verify in **Settings > Developer > Extensions** that the Spotify extension is listed.
2. **Authenticate with Spotify**:
- If no valid tokens exist, run the server manually to get the login URL:
```bash
cd C:\Users\anush\AppData\Local\AnthropicClaude\app-0.12.28
C:\Users\anush\AppData\Local\Programs\Python\Python313\python.exe main.py --client-id your_client_id_here --client-secret your_client_secret_here
```
- Look for the authentication URL in the output:
```
--- SPOTIFY AUTHENTICATION REQUIRED ---
Please open this URL in your browser to log in to Spotify:
https://accounts.spotify.com/authorize?client_id=...&response_type=code&redirect_uri=http%3A%2F%2F127.0.0.1%3A8080%2Fcallback&scope=...
```
- Open the URL in a browser, log in to Spotify, and authorize the app.
- The callback will save tokens to `user_tokens.json`.
3. **Control Spotify**:
- In Claude Desktop, use commands like:
- “Play the song Loverboy”
- “Pause playback”
- “Create a playlist named Summer Hits”
- “Add Blinding Lights by The Weeknd to Summer Hits”
- “Set volume to 50”
- Ensure Spotify is running with an active device.
4. **Test via Command Line** (Optional):
```bash
cd C:\Users\anush\AppData\Local\AnthropicClaude\app-0.12.28
echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "play_song", "arguments": {"song_title": "Loverboy"}}, "id": 9}' | C:\Users\anush\AppData\Local\Programs\Python\Python313\python.exe main.py --client-id your_client_id_here --client-secret your_client_secret_here
```
## Supported Tools
- `play_song(song_title, artist?)`: Plays a song (artist optional for accuracy).
- `pause_playback()`: Pauses current playback.
- `resume_playback()`: Resumes paused playback.
- `skip_track()`: Skips to the next track.
- `previous_track()`: Returns to the previous track.
- `set_volume(volume_percent)`: Sets volume (0-100).
- `create_playlist(playlist_name, public?)`: Creates a playlist (public defaults to true).
- `add_to_playlist(song_title, playlist_name, artist?)`: Adds a song to a playlist.
- `get_current_playback_info()`: Retrieves current song and playback state.
## Support
For issues, consult the MCP debugging documentation or share:
- `mcp-server-Spotify.log` (redact sensitive data).
- Relevant error messages from Claude Desktop or command line.
