{"id":"2b179aa9-17b0-4428-8c9b-ed7392e6a412","slug":"spotify-mcp","kind":"mcp","name":"spotify-mcp","summary":"Control Spotify from Claude, Cursor, or any MCP client. 100+ tools for playback, playlists, discovery, and curation.","owner":"gupta-kush","repoUrl":"https://github.com/gupta-kush/spotify-mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":9,"match":null,"fewStars":false,"format":"mcp","createdAt":"2026-03-06T21:57:57.000Z","addedAt":"2026-10-14T05:08:17.268Z","logoUrl":"https://avatars.githubusercontent.com/u/54411218?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","memory-knowledge"],"tags":["ai","claude","fastmcp","llm-tools","python","spotify","spotify-api"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-17T09:35:40.109Z","sample":false,"url":"https://conduits.dev/tools/spotify-mcp","language":"Python","transports":["stdio"],"install":{"pypi":"spotify-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<!-- mcp-name: io.github.gupta-kush/spotify-mcp -->\n# Spotify MCP Server\n\n[![PyPI](https://img.shields.io/pypi/v/spotify-mcp)](https://pypi.org/project/spotify-mcp/)\n[![Tests](https://github.com/gupta-kush/spotify-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/gupta-kush/spotify-mcp/actions/workflows/test.yml)\n![100+ Tools](https://img.shields.io/badge/tools-100%2B-brightgreen)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=spotify&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJzcG90aWZ5LW1jcCJdLCJlbnYiOnsiU1BPVElGWV9DTElFTlRfSUQiOiJ5b3VyX2NsaWVudF9pZCJ9fQ==)\n\nControl 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.\n\n<!-- TODO: Replace with actual demo GIF -->\n\n## Quick Start\n\n### 1. Get a Spotify Client ID\n\nGo to the [Spotify Developer Dashboard](https://developer.spotify.com/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).\n\n### 2. Install and Configure\n\n**Claude Code** (one command):\n\n```bash\nclaude mcp add spotify -- uvx spotify-mcp\n```\n\nThen set your client ID: `claude mcp add spotify -e SPOTIFY_CLIENT_ID=your_client_id -- uvx spotify-mcp`\n\n**Claude Desktop** (add to `claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"spotify\": {\n      \"command\": \"uvx\",\n      \"args\": [\"spotify-mcp\"],\n      \"env\": {\n        \"SPOTIFY_CLIENT_ID\": \"your_client_id\"\n      }\n    }\n  }\n}\n```\n\n**Cursor / VS Code** (same config, but load only core tools to stay under the 40-tool limit):\n\n```json\n{\n  \"mcpServers\": {\n    \"spotify\": {\n      \"command\": \"uvx\",\n      \"args\": [\"spotify-mcp\", \"--toolsets=core\"],\n      \"env\": {\n        \"SPOTIFY_CLIENT_ID\": \"your_client_id\"\n      }\n    }\n  }\n}\n```\n\nOr install with pip: `pip install spotify-mcp`\n\n### 3. Authorize\n\nThe first time you use a Spotify tool, your browser opens for OAuth. Grant access and the token is cached locally.\n\n## Why this one?\n\nThere are 30+ Spotify MCP servers out there. Most have 10-15 tools covering play, pause, and search.\n\n| | spotify-mcp | Typical server |\n|---|---|---|\n| **Tools** | **100+** | 5-15 |\n| **Smart shuffle** (6 strategies incl. energy arcs) | Yes | No |\n| **Vibe engine** (mood analysis without audio-features) | Yes | No |\n| **Natural language song search** | Yes | No |\n| **Artist network mapping** (100 related artists) | Yes | No |\n| **Taste evolution tracking** | Yes | No |\n| **Library index** (AI playlists from your own songs) | Yes | No |\n| **Destructive tools stripped by default** | Yes | No |\n| **Merge / diff / deduplicate** playlists | Yes | No |\n| **Works after Feb 2026 API changes** | Yes | Most broke |\n| **PKCE auth** (no client secret needed) | Yes | Rare |\n\n## What can you do with it?\n\nSome things you can ask:\n\n- \"Play Bohemian Rhapsody\"\n- \"Make my playlist start chill and build to high energy\"\n- \"Find that sad song with strings by Pink Floyd from the 90s\"\n- \"How has my music taste changed over time?\"\n- \"Map Radiohead's related artist network\"\n- \"Compare my Gym and Running playlists\"\n- \"Clean up my old playlist\" (removes unavailable tracks and duplicates)\n- \"What's the vibe of my Summer playlist?\"\n- \"Create a radio playlist based on Radiohead\"\n- \"When do I listen to music the most?\"\n\n## Toolsets\n\nAll tools load by default, minus destructive tools (see [Safety](#safety)). For clients with tool limits, use `--toolsets`:\n\n```bash\nspotify-mcp --toolsets=core              # ~27 tools: playback, playlists, search, library, browse, stats\nspotify-mcp --toolsets=core,discovery    # Add music discovery\nspotify-mcp --toolsets=core,power        # Add power tools (smart shuffle, vibe engine, etc.)\nspotify-mcp --toolsets=all               # All tools (default, destructive excluded)\nspotify-mcp --toolsets=all,destructive   # All tools including remove/unfollow\n```\n\nOr via environment variable: `SPOTIFY_MCP_TOOLSETS=core,power`\n\nAvailable toolsets: `core`, `social`, `discovery`, `power`, `destructive`, `all`\n\n## Safety\n\nDestructive 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.\n\nAffected 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`\n\nEven when enabled, destructive tools default to `dry_run=True`, showing a preview without executing. Pass `dry_run=False` to perform the action.\n\n## Tool Reference\n\n<details>\n<summary><strong>Playback (15 tools)</strong></summary>\n\n| Tool | Description |\n|------|-------------|\n| `spotify_status` | Connection status and current playback |\n| `spotify_now_playing` | Currently playing track details |\n| `spotify_play` | Start playback (track, album, or playlist) |\n| `spotify_pause` | Pause playback |\n| `spotify_resume` | Resume playback |\n| `spotify_skip_next` | Skip to next track |\n| `spotify_skip_previous` | Skip to previous track |\n| `spotify_add_to_queue` | Add a track to the queue |\n| `spotify_get_queue` | View the playback queue |\n| `spotify_get_devices` | List available Spotify Connect devices |\n| `spotify_set_volume` | Set volume (0-100) |\n| `spotify_seek` | Seek to a position in the current track |\n| `spotify_set_repeat` | Set repeat mode (off/context/track) |\n| `spotify_toggle_shuffle` | Toggle shuffle on or off |\n| `spotify_transfer_playback` | Transfer playback to another device |\n\n</details>\n\n<details>\n<summary><strong>Playlists (12 tools)</strong></summary>\n\n| Tool | Description |\n|------|-------------|\n| `spotify_get_my_playlists` | List your playlists |\n| `spotify_get_playlist` | Get playlist details and tracks |\n| `spotify_get_playlist_tracks` | Get playlist tracks with pagination |\n| `spotify_create_playlist` | Create a new playlist |\n| `spotify_add_to_playlist` | Add tracks to a playlist |\n| `spotify_remove_from_playlist` | Remove tracks from a playlist |\n| `spotify_reorder_playlist` | Move tracks within a playlist |\n| `spotify_update_playlist` | Update name, description, or visibility |\n| `spotify_follow_playlist` | Follow a playlist |\n| `spotify_unfollow_playlist` | Unfollow a playlist |\n| `spotify_get_playlist_cover` | Get the playlist's cover image URL |\n| `spotify_check_playlist_followers` | Check if users follow a playlist |\n\n</details>\n\n<details>\n<summary><strong>Search & Discovery (6 tools)</strong></summary>\n\n| Tool | Description |\n|------|-------------|\n| `spotify_search` | Search for tracks, artists, albums, or playlists |\n| `spotify_related_artists` | Find artists similar to a given artist |\n| `spotify_discover_by_artist` | Discover tracks via related artists |\n| `spotify_discover_by_mood` | Find tracks matching a mood |\n| `spotify_genre_explorer` | Explore tracks and artists in a genre |\n| `spotify_discover_deep_cuts` | Find album-only tracks (not singles) |\n\n</details>\n\n<details>\n<summary><strong>Stats & Insights (7 tools)</strong></summary>\n\n| Tool | Description |\n|------|-------------|\n| `spotify_top_tracks` | Your top tracks by time range |\n| `spotify_top_artists` | Your top artists by time range |\n| `spotify_recently_played` | Recent listening history |\n| `spotify_listening_patterns` | When you listen (hour and day distributions) |\n| `spotify_taste_profile` | Genre diversity and niche artist analysis |\n| `spotify_playlist_compare` | Compare multiple playlists side by side |\n| `spotify_playlist_freshness` | When each playlist was last updated, sorted by staleness |\n\n</details>\n\n<details>\n<summary><strong>Library (9 tools)</strong></summary>\n\n| Tool | Description |\n|------|-------------|\n| `spotify_get_saved_tracks` | Your liked/saved tracks |\n| `spotify_save_tracks` | Save tracks to Liked Songs |\n| `spotify_remove_saved_tracks` | Remove tracks from Liked Songs |\n| `spotify_get_saved_albums` | Your saved albums |\n| `spotify_save_albums` | Save albums to library |\n| `spotify_remove_saved_albums` | Remove albums from library |\n| `spotify_check_saved_tracks` | Check if tracks are in Liked Songs |\n| `spotify_check_saved_albums` | Check if albums are in your library |\n| `spotify_get_saved_episodes` | Your saved podcast episodes |\n\n</details>\n\n<details>\n<summary><strong>Follow & Social (7 tools)</strong></summary>\n\n| Tool | Description |\n|------|-------------|\n| `spotify_follow_artists` | Follow artists |\n| `spotify_unfollow_artists` | Unfollow artists |\n| `spotify_get_followed_artists` | List your followed artists |\n| `spotify_check_following_artists` | Check if you follow specific artists |\n| `spotify_check_following_users` | Check if you follow specific users |\n| `spotify_follow_users` | Follow Spotify users |\n| `spotify_unfollow_users` | Unfollow Spotify users |\n\n</details>\n\n<details>\n<summary><strong>Shows & Podcasts (8 tools)</strong></summary>\n\n| Tool | Description |\n|------|-------------|\n| `spotify_get_saved_shows` | Your saved podcasts and shows |\n| `spotify_get_show` | Get show details |\n| `spotify_get_show_episodes` | List episodes of a show |\n| `spotify_save_shows` | Save shows to your library |\n| `spotify_remove_saved_shows` | Remove shows from your library |\n| `spotify_check_saved_shows` | Check if shows are in your library |\n| `spotify_save_episodes` | Save individual episodes |\n| `spotify_get_episode` | Get episode details (duration, resume point) |\n\n</details>\n\n<details>\n<summary><strong>Browse (5 tools)</strong></summary>\n\n| Tool | Description |\n|------|-------------|\n| `spotify_get_track` | Full track details (popularity, ISRC, preview URL) |\n| `spotify_get_album` | Album details with full tracklist |\n| `spotify_get_artist` | Artist profile (followers, popularity, genres) |\n| `spotify_get_artist_albums` | List an artist's albums, singles, and compilations |\n| `spotify_get_user` | User profile with public playlists |\n\n</details>\n\n<details>\n<summary><strong>Playlist Power Tools (8 tools)</strong></summary>\n\n| Tool | Description |\n|------|-------------|\n| `spotify_merge_playlists` | Merge multiple playlists into one |\n| `spotify_split_playlist_by_artist` | Split a playlist by artist |\n| `spotify_deduplicate_playlist` | Remove duplicate tracks |\n| `spotify_export_playlist` | Export playlist data |\n| `spotify_playlist_diff` | Compare track differences between playlists |\n| `spotify_find_playlist_overlaps` | Scan all playlists for shared tracks |\n| `spotify_find_playlist_subsets` | Find playlists that are subsets of others |\n| `spotify_absorb_playlist` | Merge unique tracks from one playlist into another |\n\n</details>\n\n<details>\n<summary><strong>Reports & Analytics (3 tools)</strong></summary>\n\n| Tool | Description |\n|------|-------------|\n| `spotify_listening_report` | Full listening profile with genres and stats |\n| `spotify_playlist_analysis` | Analyze playlist composition |\n| `spotify_taste_evolution` | How your taste has changed over time |\n\n</details>\n\n<details>\n<summary><strong>Smart Shuffle (1 tool, 6 strategies)</strong></summary>\n\n| Tool | Description |\n|------|-------------|\n| `spotify_smart_shuffle` | Reorder a playlist: variety, alphabetical_artist, chronological, genre_variety, energy_arc, reverse_chronological |\n\n</details>\n\n<details>\n<summary><strong>Playlist Generators (4 tools)</strong></summary>\n\n| Tool | Description |\n|------|-------------|\n| `spotify_create_radio` | Create a radio playlist from a seed track or artist |\n| `spotify_time_capsule` | Snapshot your current top tracks into a playlist |\n| `spotify_vibe_playlist` | Create a mood-based playlist |\n| `spotify_era_playlist` | Create a decade-themed playlist |\n\n</details>\n\n<details>\n<summary><strong>Playlist Curator (4 tools)</strong></summary>\n\n| Tool | Description |\n|------|-------------|\n| `spotify_sort_playlist` | Sort by track name, artist, album, duration, or date added |\n| `spotify_cleanup_playlist` | Remove unavailable tracks and duplicates |\n| `spotify_interleave_playlists` | Interleave tracks from multiple playlists |\n| `spotify_playlist_radio` | Create a radio playlist from a playlist's top artists |\n\n</details>\n\n<details>\n<summary><strong>Queue Builder (2 tools)</strong></summary>\n\n| Tool | Description |\n|------|-------------|\n| `spotify_build_queue` | Add multiple tracks to the queue in order |\n| `spotify_queue_from_playlist` | Queue tracks from a playlist |\n\n</details>\n\n<details>\n<summary><strong>Vibe Engine (2 tools)</strong></summary>\n\n| Tool | Description |\n|------|-------------|\n| `spotify_playlist_vibe` | Analyze a playlist's genre vibe and energy |\n| `spotify_find_vibe_matches` | Find tracks that match a playlist's vibe |\n\n</details>\n\n<details>\n<summary><strong>Artist Explorer (3 tools)</strong></summary>\n\n| Tool | Description |\n|------|-------------|\n| `spotify_artist_deep_dive` | Full artist profile with discography and stats |\n| `spotify_artist_timeline` | Artist's career timeline with all releases |\n| `spotify_artist_network` | Map an artist's related artist network |\n\n</details>\n\n<details>\n<summary><strong>Find Song (1 tool)</strong></summary>\n\n| Tool | Description |\n|------|-------------|\n| `spotify_find_song` | Find a song using natural language description |\n\n</details>\n\n<details>\n<summary><strong>Library Index (3 tools)</strong></summary>\n\nSync your Spotify library to a local index, then let your AI create playlists from songs you already know instead of random catalog tracks.\n\n| Tool | Description |\n|------|-------------|\n| `spotify_sync_library` | Sync liked songs and your playlists to a local JSON index |\n| `spotify_library_stats` | Artist counts, playlist names, and dates (compact overview for AI reasoning) |\n| `spotify_query_library` | Filter your library by artist, playlist, date range, track/album name |\n\n**Example:** \"Make a playlist with my favorite indie rock songs from this year.\" The AI checks your library stats, picks matching artists, queries by date range, and builds a playlist from songs you already have.\n\nData stored at `%LOCALAPPDATA%\\spotify-mcp\\library.json` (Windows) or `~/.cache/spotify-mcp/library.json` (Linux/Mac). Only syncs playlists you created.\n\n</details>\n\n## Setup Options\n\n### Environment Variables (Recommended)\n\nSet `SPOTIFY_CLIENT_ID` (and optionally `SPOTIFY_CLIENT_SECRET`) in your MCP client config's `env` field.\n\n### Interactive Setup\n\n```bash\nspotify-mcp-setup\n```\n\nWalks you through credentials and saves them to `~/.config/spotify-mcp/.env` (Linux/Mac) or `%APPDATA%\\spotify-mcp\\.env` (Windows).\n\n### Manual .env File\n\nCreate `.env` in `~/.config/spotify-mcp/` (or `%APPDATA%\\spotify-mcp\\` on Windows):\n\n```\nSPOTIFY_CLIENT_ID=your_client_id\nSPOTIFY_REDIRECT_URI=http://127.0.0.1:8888/callback\n```\n\nAdd `SPOTIFY_CLIENT_SECRET=your_secret` if you prefer traditional OAuth over PKCE.\n\n## Finding Spotify IDs\n\nMost tools accept IDs, URIs, or URLs interchangeably:\n\n- **Search first:** Use `spotify_search` to find anything by name\n- **Copy from Spotify:** Right-click any item -> Share -> Copy Spotify URI\n- **From URLs:** `https://open.spotify.com/track/4uLU6hMCjMI75M1A2tKUQC` -> `4uLU6hMCjMI75M1A2tKUQC`\n\n## Spotify's Feb 2026 API Changes\n\nSpotify [removed several endpoints](https://developer.spotify.com/blog/2026-02-06-update-on-developer-access-and-platform-security) 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.\n\nThis 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.\n\n## Architecture\n\n```\nspotify_mcp/\n├── server.py                      # FastMCP entry + toolset loading\n├── auth.py                        # OAuth / PKCE auth singleton\n├── config.py                      # Constants, genre maps, toolset definitions\n├── tools/                         # Core tools (playback, playlists, search, etc.)\n├── power/                         # Power tools (smart shuffle, vibe engine, etc.)\n└── utils/                         # Shared utilities (client, errors, formatting)\n```\n\n## Troubleshooting\n\n### \"No active device found\"\nOpen Spotify on any device before using playback commands.\n\n### OAuth redirect fails\nEnsure the redirect URI **exactly** matches the Spotify Developer Dashboard. Default: `http://127.0.0.1:8888/callback` (not https).\n\n### Token expired or corrupted\nDelete `.spotify_token_cache` from `~/.cache/spotify-mcp/` (or `%LOCALAPPDATA%\\spotify-mcp\\`) and restart.\n\n### Premium-only features\nVolume, seek, transfer, shuffle, and repeat require Spotify Premium.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code conventions, and how to add new tools.\n\n## License\n\n[MIT](LICENSE)\n\n---\n\nIf you find this useful, a star helps others find it too.\n"}