io.github.khglynn/spotify-bulk-actions-mcp
MCP server for bulk Spotify operations - batch playlist creation, exports, management
Open source Open in the app JSON README (API)
About
MCP server for bulk Spotify operations - batch playlist creation, exports, management
Details
- Kind
- MCP servers
- Topic
- Media, design & games
- Publisher
- khglynn
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.1
- Stars
- 2
- Forks
- 2
- Last push
- 2026-08-11T02:29:30Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:00:20
- Updated
- 2026-08-29 04:00:20
- Origin id
io.github.khglynn/spotify-bulk-actions-mcp
README
<p align="center">
<img src="logo.png" alt="Spotify Bulk Actions MCP" width="200">
</p>
# Spotify Bulk Actions MCP
<!-- mcp-name: io.github.khglynn/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)!