Spotify MCP Server

Spotify MCP Server

Control Spotify from Claude, Cursor, or any MCP client. 93 tools -- not just play/pause, but smart shuffling, vibe analysis, natural language song search, artist network mapping, taste evolution tracking, and way more. Built for Spotify's post-February 2026 API where most other servers broke.

Why this one?

There are 30+ Spotify MCP servers out there. Most give you 10-15 tools covering play, pause, search, done. This one goes deeper:

Quick Start

1. Install

uvx spotify-mcp

Or with pip:

pip install spotify-mcp

2. Get Spotify Credentials

1. Go to the Spotify Developer Dashboard
2. Click Create App
3. Set the Redirect URI to http://127.0.0.1:8888/callback
4. Check Web API and click Save
5. Copy your Client ID (Client Secret is optional -- PKCE auth works without it)

3. Configure Your Client

Claude Desktop -- add to claude_desktop_config.json:

{
  "mcpServers": {
    "spotify": {
      "command": "uvx",
      "args": ["spotify-mcp"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id"
      }
    }
  }
}

Cursor / VS Code -- use the same config, but load only core tools to stay under the 40-tool limit:

{
  "mcpServers": {
    "spotify": {
      "command": "uvx",
      "args": ["spotify-mcp", "--toolsets=core"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id"
      }
    }
  }
}

4. First Run

The first time you use a Spotify tool, your browser opens for OAuth authorization. Grant access and the token is cached locally.

What can you do with it?

Just talk to your AI assistant like you'd talk to a friend who has access to your Spotify:

• "Play Bohemian Rhapsody"
• "Make my playlist start chill and build to high energy" -- smart shuffle reorders it with an energy arc
• "Find that sad song with strings by Pink Floyd from the 90s" -- natural language, not exact titles
• "How has my music taste changed over time?" -- compares your short/medium/long term listening
• "Map Radiohead's related artist network" -- explores up to 100 connected artists
• "Create a 90s era playlist"
• "Compare my Gym and Running playlists" -- side-by-side genre and artist breakdown
• "Clean up my old playlist" -- finds and removes unavailable tracks and duplicates
• "What's the vibe of my Summer playlist?" -- genre-based energy and mood analysis
• "Create a radio playlist based on Radiohead" -- samples related artists' catalogs
• "When do I listen to music the most?" -- hour-of-day and day-of-week patterns

Toolsets

By default, all 93 tools are loaded. For clients with tool limits (Cursor: 40 max), use --toolsets to load only what you need:

spotify-mcp --toolsets=core              # ~27 tools: playback, playlists, search, library, browse, stats
spotify-mcp --toolsets=core,discovery    # Add music discovery
spotify-mcp --toolsets=core,power        # Add power tools (smart shuffle, vibe engine, etc.)
spotify-mcp --toolsets=all               # All 93 tools (default)

Or via environment variable: SPOTIFY_MCP_TOOLSETS=core,power

Available toolsets: core, social, discovery, power, all

Tool Reference

Setup Options

Option A: Environment Variables (Recommended)

Set SPOTIFY_CLIENT_ID (and optionally SPOTIFY_CLIENT_SECRET) in your MCP client config's env field. This is the simplest approach.

Option B: Interactive Setup

spotify-mcp-setup

Walks you through entering credentials and saves them to ~/.config/spotify-mcp/.env (Linux/Mac) or %APPDATA%\spotify-mcp\.env (Windows).

Option C: Manual .env File

Create .env in ~/.config/spotify-mcp/ (or %APPDATA%\spotify-mcp\ on Windows):

SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888/callback

Add SPOTIFY_CLIENT_SECRET=your_secret if you prefer the traditional OAuth flow over PKCE.

Authentication Modes

• PKCE (default): Only needs SPOTIFY_CLIENT_ID. No client secret required. Recommended for most users.
• OAuth: If SPOTIFY_CLIENT_SECRET is also set, uses the traditional OAuth flow. Backward-compatible with existing setups.

Finding Spotify IDs

Most tools accept Spotify IDs, URIs, or URLs interchangeably:

• Search first: Use spotify_search to find anything by name
• Copy from Spotify: Right-click any item -> Share -> Copy Spotify URI
• From URLs: https://open.spotify.com/track/4uLU6hMCjMI75M1A2tKUQC -> 4uLU6hMCjMI75M1A2tKUQC

A note on Spotify's Feb 2026 API changes

Spotify removed a bunch of endpoints in February 2026: audio-features, audio-analysis, recommendations, artist/top-tracks, all batch endpoints, and browse/categories. Search is now capped at 10 results per page. Most Spotify MCP servers just... broke.

This server was built with those constraints in mind. Discovery uses search + related artists + genre mapping instead of the old recommendations API. The vibe engine estimates energy from artist genre data rather than the now-dead audio-features endpoint. It's not perfect, but it works.

Architecture

spotify_mcp/
├── server.py                      # FastMCP entry + toolset loading
├── auth.py                        # OAuth / PKCE auth singleton
├── config.py                      # Constants, genre maps, toolset definitions
├── tools/                         # Core tools (playback, playlists, search, etc.)
├── power/                         # Power tools (smart shuffle, vibe engine, etc.)
└── utils/                         # Shared utilities (client, errors, formatting)

Troubleshooting

"No active device found"

Open Spotify on any device before using playback commands.

OAuth redirect fails

Ensure the redirect URI in your config exactly matches the Spotify Developer Dashboard. Default: http://127.0.0.1:8888/callback (not https).

Token expired or corrupted

Delete .spotify_token_cache from ~/.cache/spotify-mcp/ (or %LOCALAPPDATA%\spotify-mcp\) and restart.

Premium-only features

Volume, seek, transfer, shuffle, and repeat require Spotify Premium.

Contributing

See CONTRIBUTING.md for development setup, code conventions, and how to add new tools.

License

MIT

If this is useful to you, a star on the repo goes a long way. It helps other people find it.