# Spotify Bulk Actions MCP A Model Context Protocol (MCP) server for bulk Spotify operations - **batch playlist creation, library exports, and large-scale library management.** **What makes this different from other Spotify MCPs?** - **Confidence scoring** - Batch searches return HIGH/MEDIUM/LOW confidence for each match - **Human-in-the-loop** - Uncertain matches are exported for review, then re-imported - **Bulk operations** - Handle 500+ songs efficiently with rate limiting built-in - **Library exports** - Export your complete library data - **Podcast playlist focused** - Built specifically for importing song lists from podcast show notes --- ## Support This Project Made cause I can't not have headphones on, support my 80k+ pocast subscriptions. [](https://buymeacoffee.com/kevinhg) --- ## Listed On | Directory | Link | |-----------|------| | PyPI | [pypi.org/project/spotify-bulk-actions-mcp](https://pypi.org/project/spotify-bulk-actions-mcp/) | | mcp.so | [mcp.so/server/spotify-bulk-actions-mcp](https://mcp.so/server/spotify-bulk-actions-mcp/khglynn) | | awesome-mcp-servers | [PR #1541](https://github.com/punkpeye/awesome-mcp-servers/pull/1541) *(pending)* | --- ## Projects I've Built With This | Project | Description | Links | |---------|-------------|-------| | **recordOS** | Which albums do you love most? A visual album collection app | [Live](https://record-os.khglynn.com) · [Repo](https://github.com/khglynn/recordOS) | | **Festival Navigator** | Navigate multi-day festivals with friends | [Repo](https://github.com/khglynn/festival-navigator) | ### Playlists Maintained With This MCP *Coming soon: Switched On Pop, This American Life, and more podcast playlists* --- ## What This Does **Library Analysis:** - Get all your followed artists - Get all saved/liked songs (handles libraries up to 10k songs) - Find unique artists from your library ranked by song count - Find albums where you have 6+ saved songs (great for vinyl shopping!) - Export your complete library summary **Listening Insights:** - Your top artists and tracks (short/medium/long term) - Recently played history **Bulk Playlist Creation:** - Import song lists from CSV files (for podcast playlists, etc.) - Batch search with confidence scoring (HIGH/MEDIUM/LOW) - Automatic handling of uncertain matches for human review - Create playlists from search results **Playlist Maintenance:** - Find and remove duplicate tracks - Compare two playlists (shared vs unique tracks) - Bulk remove and reorder tracks, update playlist details - Export any playlist to CSV **Bulk Library Actions:** - Follow/unfollow artists in bulk - Save/unsave tracks in bulk ## Quick Start ### 1. Prerequisites - Python 3.10+ - A Spotify account - Spotify Developer credentials ([get them here](https://developer.spotify.com/dashboard)) ### 2. Clone & Setup ```bash # Clone the repo git clone https://github.com/khglynn/spotify-bulk-actions-mcp.git cd spotify-bulk-actions-mcp # Create and activate virtual environment python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate # Install the package pip install -e . # Copy env example and add your credentials cp .env.example .env # Edit .env with your SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET ``` > **Also on PyPI:** `pip install spotify-bulk-actions-mcp` - but you'll still need local `.env` and auth setup. ### 3. Authenticate with Spotify (One-Time) This opens a browser for you to log in: ```bash python setup_auth.py ``` After login, your token is saved locally in `.spotify_cache/`. ### 4. Test It Works ```bash source venv/bin/activate python -c "from spotify_bulk_actions_mcp.utils.auth import is_authenticated; print('Auth OK!' if is_authenticated() else 'Not authenticated')" ``` ### Option B: Hosted (claude.ai custom connector) This server also runs as a remote MCP over streamable HTTP (`MCP_TRANSPORT=http`), fronted by OAuth 2.1 (WorkOS AuthKit) with a fail-closed user allowlist. That's how the author runs it: Cloud Run + Secret Manager for the Spotify refresh token, added to claude.ai as a custom connector. Tools carry `readOnlyHint`/`destructiveHint` annotations so clients can group read vs write actions. See `Dockerfile` and the deploy notes in the parent collection repo. ### 5. Connect to Claude Code Add this to your Claude Code settings (`~/.claude/settings.local.json`): ```json { "mcpServers": { "spotify": { "command": "/path/to/spotify-bulk-actions-mcp/venv/bin/spotify-bulk-actions-mcp" } } } ``` Restart Claude Code after adding this. ## Available Tools (33) ### Library Analysis | Tool | Description | |------|-------------| | `check_auth_status` | Verify Spotify auth is working | | `get_followed_artists` | Get all artists you follow | | `get_saved_tracks` | Get all your liked songs | | `get_library_artists` | Artists from saved songs, ranked by count | | `get_albums_by_song_count` | Albums with N+ saved songs | | `export_library_summary` | Complete library export | ### Listening Insights | Tool | Description | |------|-------------| | `get_top_artists` | Your top artists (short/medium/long term) | | `get_top_tracks` | Your top tracks (short/medium/long term) | | `get_recently_played` | Recently played tracks | ### Bulk Library Actions | Tool | Description | |------|-------------| | `follow_artists` | Follow artists in bulk | | `unfollow_artists` | Unfollow artists in bulk | | `save_tracks` | Like/save tracks in bulk | | `unsave_tracks` | Un-like tracks in bulk | ### Search | Tool | Description | |------|-------------| | `search_track` | Search for a single track | | `search_track_fuzzy` | Broader search when exact fails | | `batch_search_tracks` | Search many tracks with confidence scores | | `get_track_preview_url` | Get 30-second preview URL | ### Playlist Creation | Tool | Description | |------|-------------| | `create_playlist` | Create a new playlist | | `add_tracks_to_playlist` | Add tracks to existing playlist | | `import_and_create_playlist` | Full CSV → playlist workflow | | `create_playlist_from_search_results` | Create from batch search | | `add_reviewed_tracks` | Add reviewed/corrected tracks | ### Playlist Management | Tool | Description | |------|-------------| | `get_playlist_info` | Get playlist details | | `update_playlist` | Update name, description, public status | | `get_playlist_tracks` | Get all tracks in a playlist | | `export_playlist_to_csv` | Export a playlist to CSV | | `compare_playlists` | Shared vs unique tracks between two playlists | | `find_duplicate_tracks` | Find duplicates in a playlist | | `remove_duplicate_tracks` | Remove duplicates, keeping first occurrence | | `remove_tracks_from_playlist` | Bulk remove specific tracks | | `reorder_playlist_tracks` | Move tracks within a playlist | ### Utilities | Tool | Description | |------|-------------| | `parse_song_list_csv` | Validate a song CSV | | `export_review_csv` | Export uncertain matches for review | ## How This Differs From the Official Spotify Connector Claude has an official Spotify connector (built by Spotify, April 2026). It's excellent at what it does — but its tool surface is small, and this MCP exists for everything it doesn't cover. As of August 2026 the official connector exposes 8 tools: Search Spotify, Create Playlist, Get Currently Playing, Add to Library, Remove from Library, Fetch Playlist Tracks, and two auth utilities. | Capability | Official connector | This MCP | |---|---|---| | Search, playback context, mood playlists | ✅ | Search only | | Create a playlist | ✅ | ✅ (plus CSV import w/ confidence scoring) | | Add/remove Liked Songs | ✅ (one at a time) | ✅ bulk | | Read your full library (saved tracks, followed artists) | ❌ | ✅ | | Listening insights (top artists/tracks, recently played) | ❌ | ✅ | | Edit existing playlists (bulk remove, reorder, update details) | ❌ | ✅ | | Dedupe / compare / export playlists to CSV | ❌ | ✅ | | Bulk follow/unfollow artists | ❌ | ✅ | One more difference: the official connector runs on Spotify's partner-gated MCP gateway (no dynamic client registration; tokens from ordinary developer apps are rejected), so it's only usable inside partnered AI surfaces. This MCP runs under your own Spotify developer app — Development Mode limits apply (5 allowlisted users per Client ID as of February 2026), but you control it end to end. ## Example Workflows ### Get Your Library Stats Ask Claude: > "What artists do I have the most saved songs from?" Claude will use `get_library_artists` and show you. ### Find Albums for Vinyl Ask Claude: > "Find albums where I have 6 or more saved songs" Claude will use `get_albums_by_song_count` with `min_songs=6`. ### Create Playlist from Song List 1. Create a CSV file: ```csv title,artist Bohemian Rhapsody,Queen Hotel California,Eagles Billie Jean,Michael Jackson ``` 2. Ask Claude: > "Create a playlist called 'My Mix' from this CSV: [paste CSV]" Claude will: 1. Parse the CSV 2. Search each song with confidence scoring 3. Create the playlist with high-confidence matches 4. Show you uncertain matches to review ### Bulk Podcast Playlist For large lists (500+ songs): 1. Ask Claude to use `batch_search_tracks` with your song list 2. Review the results (HIGH goes in automatically) 3. Use `export_review_csv` to get uncertain matches 4. Review/correct in a spreadsheet 5. Use `add_reviewed_tracks` to add your corrections ## Rate Limits The server handles Spotify's rate limits automatically: - Small delays between API calls - Automatic retry on 429 errors - Caching to reduce repeat calls For 10k songs, expect the initial library fetch to take 2-3 minutes. ## Files & Data | Location | Purpose | |----------|---------| | `.env` | Your Spotify credentials (gitignored) | | `.spotify_cache/` | Auth tokens and cached data (gitignored) | | `spotify_bulk_actions_mcp/server.py` | Main MCP server | | `spotify_bulk_actions_mcp/tools/` | Tool implementations | ## Troubleshooting **"Not authenticated" error:** ```bash python setup_auth.py ``` **Rate limit errors:** Wait a few minutes and try again. The server will auto-retry. **Token expired:** The server auto-refreshes tokens. If issues persist, re-run `setup_auth.py`. ## Security Notes - Your credentials are in `.env` (gitignored, never committed) - Auth tokens are stored locally in `.spotify_cache/` - Never share your `.env` or token files - If credentials are exposed, rotate them in Spotify Dashboard ## License MIT --- Made cause I can't not have headphones on. If this helps you, [buy me a coffee](https://buymeacoffee.com/kevinhg)!