Spotify MCP Server

Control Spotify from Claude, Cursor, or any MCP client. 100+ tools for playback, search, playlist management, smart shuffle, vibe analysis, natural language song search, artist exploration, and library indexing. Just uvx spotify-mcp to get started.

Quick Start

1. Get a Spotify Client ID

Go to the Spotify Developer Dashboard, create an app, set the redirect URI to http://127.0.0.1:8888/callback, check Web API, and copy your Client ID. No client secret needed (PKCE auth).

2. Install and Configure

Claude Code (one command):

claude mcp add spotify -- uvx spotify-mcp

Then set your client ID: claude mcp add spotify -e SPOTIFY_CLIENT_ID=your_client_id -- uvx spotify-mcp

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 (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"
      }
    }
  }
}

Or install with pip: pip install spotify-mcp

3. Authorize

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

Why this one?

There are 30+ Spotify MCP servers out there. Most have 10-15 tools covering play, pause, and search.

What can you do with it?

Some things you can ask:

• “Play Bohemian Rhapsody”
• “Make my playlist start chill and build to high energy”
• “Find that sad song with strings by Pink Floyd from the 90s”
• “How has my music taste changed over time?”
• “Map Radiohead’s related artist network”
• “Compare my Gym and Running playlists”
• “Clean up my old playlist” (removes unavailable tracks and duplicates)
• “What’s the vibe of my Summer playlist?”
• “Create a radio playlist based on Radiohead”
• “When do I listen to music the most?”

Toolsets

All tools load by default, minus destructive tools (see Safety). For clients with tool limits, use --toolsets:

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 tools (default, destructive excluded)
spotify-mcp --toolsets=all,destructive   # All tools including remove/unfollow

Or via environment variable: SPOTIFY_MCP_TOOLSETS=core,power

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

Safety

Destructive tools (remove tracks, unfollow artists, delete content) are not loaded unless you opt in with --toolsets=all,destructive. Safe for auto-accept mode since the AI cannot call tools that don’t exist.

Affected tools: spotify_remove_from_playlist, spotify_remove_saved_tracks, spotify_remove_saved_albums, spotify_remove_saved_shows, spotify_unfollow_playlist, spotify_unfollow_artists, spotify_unfollow_users

Even when enabled, destructive tools default to dry_run=True, showing a preview without executing. Pass dry_run=False to perform the action.

Tool Reference

Setup Options

Environment Variables (Recommended)

Set SPOTIFY_CLIENT_ID (and optionally SPOTIFY_CLIENT_SECRET) in your MCP client config’s env field.

Interactive Setup

spotify-mcp-setup

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

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 traditional OAuth over PKCE.

Finding Spotify IDs

Most tools accept 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

Spotify’s Feb 2026 API Changes

Spotify removed several endpoints in February 2026: audio-features, audio-analysis, recommendations, artist/top-tracks, all batch endpoints, and browse/categories. Search capped at 10 results per page. Most Spotify MCP servers 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 genre data rather than audio-features. 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 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 you find this useful, a star helps others find it too.