Which integrations are available for this server?

Provides extensive tools for controlling Spotify playback, managing playlists (including merging and deduplicating), discovering music through artist network mapping and vibe analysis, and tracking personal listening statistics and taste evolution.

Spotify MCP Server

PyPI Tests 93 Tools License: MIT Python 3.10+

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:

	spotify-mcp	Typical server
Tools	93	5-15
Smart shuffle (6 strategies including energy arcs)	Yes	No
Vibe engine -- mood analysis without audio-features API	Yes	No
"Find that sad piano song from the 2000s"	Yes	No
Map an artist's network of 100 related artists	Yes	No
"How has my taste changed?" -- evolution tracking	Yes	No
Merge / diff / deduplicate playlists	Yes	No
Works after Spotify's Feb 2026 API changes	Yes	Most broke
PKCE auth -- no client secret needed	Yes	Rare

Quick Start

1. Install

uvx spotify-mcp

Or with pip:

pip install spotify-mcp

2. Get Spotify Credentials

Go to the Spotify Developer Dashboard
Click Create App
Set the Redirect URI to http://127.0.0.1:8888/callback
Check Web API and click Save
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

Tool	Description
`spotify_status`	Connection status and current playback
`spotify_now_playing`	Currently playing track details
`spotify_play`	Start playback (track, album, or playlist)
`spotify_pause`	Pause playback
`spotify_resume`	Resume playback
`spotify_skip_next`	Skip to next track
`spotify_skip_previous`	Skip to previous track
`spotify_add_to_queue`	Add a track to the queue
`spotify_get_queue`	View the playback queue
`spotify_get_devices`	List available Spotify Connect devices
`spotify_set_volume`	Set volume (0-100)
`spotify_seek`	Seek to a position in the current track
`spotify_set_repeat`	Set repeat mode (off/context/track)
`spotify_toggle_shuffle`	Toggle shuffle on or off
`spotify_transfer_playback`	Transfer playback to another device

Tool	Description
`spotify_get_my_playlists`	List your playlists
`spotify_get_playlist`	Get playlist details and tracks
`spotify_get_playlist_tracks`	Get playlist tracks with pagination
`spotify_create_playlist`	Create a new playlist
`spotify_add_to_playlist`	Add tracks to a playlist
`spotify_remove_from_playlist`	Remove tracks from a playlist
`spotify_reorder_playlist`	Move tracks within a playlist
`spotify_update_playlist`	Update name, description, or visibility
`spotify_follow_playlist`	Follow a playlist
`spotify_unfollow_playlist`	Unfollow a playlist
`spotify_get_playlist_cover`	Get the playlist's cover image URL
`spotify_check_playlist_followers`	Check if users follow a playlist

Tool	Description
`spotify_search`	Search for tracks, artists, albums, or playlists
`spotify_related_artists`	Find artists similar to a given artist
`spotify_discover_by_artist`	Discover tracks via related artists
`spotify_discover_by_mood`	Find tracks matching a mood
`spotify_genre_explorer`	Explore tracks and artists in a genre
`spotify_discover_deep_cuts`	Find album-only tracks (not singles)

Tool	Description
`spotify_top_tracks`	Your top tracks by time range
`spotify_top_artists`	Your top artists by time range
`spotify_recently_played`	Recent listening history
`spotify_listening_patterns`	When you listen -- hour and day distributions
`spotify_taste_profile`	Genre diversity and niche artist analysis
`spotify_playlist_compare`	Compare multiple playlists side by side

Tool	Description
`spotify_get_saved_tracks`	Your liked/saved tracks
`spotify_save_tracks`	Save tracks to Liked Songs
`spotify_remove_saved_tracks`	Remove tracks from Liked Songs
`spotify_get_saved_albums`	Your saved albums
`spotify_save_albums`	Save albums to library
`spotify_remove_saved_albums`	Remove albums from library
`spotify_check_saved_tracks`	Check if tracks are in Liked Songs
`spotify_check_saved_albums`	Check if albums are in your library
`spotify_get_saved_episodes`	Your saved podcast episodes

Tool	Description
`spotify_follow_artists`	Follow artists
`spotify_unfollow_artists`	Unfollow artists
`spotify_get_followed_artists`	List your followed artists
`spotify_check_following_artists`	Check if you follow specific artists
`spotify_check_following_users`	Check if you follow specific users
`spotify_follow_users`	Follow Spotify users
`spotify_unfollow_users`	Unfollow Spotify users

Tool	Description
`spotify_get_saved_shows`	Your saved podcasts and shows
`spotify_get_show`	Get show details
`spotify_get_show_episodes`	List episodes of a show
`spotify_save_shows`	Save shows to your library
`spotify_remove_saved_shows`	Remove shows from your library
`spotify_check_saved_shows`	Check if shows are in your library
`spotify_save_episodes`	Save individual episodes
`spotify_get_episode`	Get episode details (duration, resume point)

Tool	Description
`spotify_get_track`	Full track details (popularity, ISRC, preview URL)
`spotify_get_album`	Album details with full tracklist
`spotify_get_artist`	Artist profile (followers, popularity, genres)
`spotify_get_user`	User profile with public playlists

Tool	Description
`spotify_merge_playlists`	Merge multiple playlists into one
`spotify_split_playlist_by_artist`	Split a playlist by artist
`spotify_deduplicate_playlist`	Remove duplicate tracks
`spotify_export_playlist`	Export playlist data
`spotify_playlist_diff`	Compare track differences between playlists
`spotify_find_playlist_overlaps`	Scan all playlists for shared tracks

Tool	Description
`spotify_listening_report`	Full listening profile with genres and stats
`spotify_playlist_analysis`	Analyze playlist composition
`spotify_taste_evolution`	How your taste has changed over time

Tool	Description
`spotify_smart_shuffle`	Reorder a playlist: variety, alphabetical_artist, chronological, genre_variety, energy_arc, reverse_chronological

Tool	Description
`spotify_create_radio`	Create a radio playlist from a seed track or artist
`spotify_time_capsule`	Snapshot your current top tracks into a playlist
`spotify_vibe_playlist`	Create a mood-based playlist
`spotify_era_playlist`	Create a decade-themed playlist

Tool	Description
`spotify_sort_playlist`	Sort by track name, artist, album, duration, or date added
`spotify_cleanup_playlist`	Remove unavailable tracks and duplicates
`spotify_interleave_playlists`	Interleave tracks from multiple playlists
`spotify_playlist_radio`	Create a radio playlist from a playlist's top artists

Tool	Description
`spotify_build_queue`	Add multiple tracks to the queue in order
`spotify_queue_from_playlist`	Queue tracks from a playlist

Tool	Description
`spotify_playlist_vibe`	Analyze a playlist's genre vibe and energy
`spotify_find_vibe_matches`	Find tracks that match a playlist's vibe

Tool	Description
`spotify_artist_deep_dive`	Comprehensive artist deep dive report
`spotify_artist_timeline`	Artist's career timeline with all releases
`spotify_artist_network`	Map an artist's related artist network

Tool	Description
`spotify_find_song`	Find a song using natural language description

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.

spotify-mcp