Spotify MCP Server

Control Spotify playback through Claude using the Model Context Protocol (MCP).

Uses PKCE authentication - just install and authorize your Spotify account.

Note: The bundled client ID works for playback control and reading data. For write operations (adding to playlists, saving to library), you'll need to set up your own Spotify app.

Quick Start

1. Install

git clone https://github.com/panuhen/spotify-mcp.git ~/spotify-mcp
cd ~/spotify-mcp
python -m venv .venv
.venv/bin/pip install -e .

2. First Run - Authenticate

Run once to authorize with your Spotify account:

~/spotify-mcp/.venv/bin/spotify-mcp

This opens your browser for Spotify login. After authorizing, the token is cached at ~/.spotify-mcp-token.

3. Add to Claude Code

Add to ~/.mcp.json:

{
  "mcpServers": {
    "spotify": {
      "command": "/home/YOUR_USER/spotify-mcp/.venv/bin/spotify-mcp"
    }
  }
}

Then enable in ~/.claude/settings.local.json:

{
  "enabledMcpjsonServers": ["spotify"]
}

Restart Claude Code and you're ready!

Available Tools

Playback Control

• play - Resume or play specific track/album/playlist
• pause - Pause playback
• next - Skip to next track
• previous - Go to previous track
• seek - Seek to position in track
• set_volume - Set volume (0-100)
• shuffle - Toggle shuffle mode
• repeat - Set repeat mode (off/track/context)

Information

• get_current_track - Get currently playing track info
• get_playback_state - Get full playback state
• get_queue - Get upcoming tracks
• get_devices - List available devices

Search & Library

• search - Search for tracks, albums, artists, playlists
• add_to_queue - Add track to queue
• get_playlists - List your playlists
• get_playlist_tracks - Get tracks from a playlist
• add_to_playlist - Add tracks to a playlist (requires own app)
• save_tracks - Save tracks to your library (requires own app)
• remove_saved_tracks - Remove tracks from library (requires own app)
• get_saved_tracks - Get your liked tracks

Local Favorites

No Spotify API permissions needed - stored locally in ~/.spotify-mcp-favorites.json:

• favorite_current - Add currently playing track to favorites
• get_favorites - List all favorited tracks
• remove_favorite - Remove a track from favorites
• play_favorites - Play random favorite or queue all favorites
• clear_favorites - Clear all favorites

Usage Examples

Once configured, you can ask Claude:

• "What song is currently playing?"
• "Pause the music"
• "Play the next track"
• "Search for 'Bohemian Rhapsody' and add it to the queue"
• "Set the volume to 50%"
• "Turn on shuffle"
• "Show my playlists"

Setup Your Own Spotify App

Required for: add_to_playlist, save_tracks, remove_saved_tracks

The bundled client ID is in Spotify's Development Mode, which restricts write operations. To use all features:

1. Create an app at https://developer.spotify.com/dashboard
2. In your app settings, add redirect URI: http://127.0.0.1:8888/callback
3. Copy your Client ID and add to ~/spotify-mcp/.env:

   SPOTIPY_CLIENT_ID=your_client_id_here
   

4. Delete cached token and re-auth:

   rm ~/.spotify-mcp-token
   

5. Restart the MCP server

Troubleshooting

"No active device" error

Make sure Spotify is open on at least one device (phone, desktop app, web player).

Authentication issues

Delete ~/.spotify-mcp-token and run spotify-mcp again to re-authenticate.

Token expired

The token auto-refreshes, but if issues persist, delete ~/.spotify-mcp-token and re-auth.