{ "markdown": "

\n \"Spotify\n

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