Spotify Bulk Actions Mcp

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.

---

Listed On

Directory	Link
PyPI	pypi.org/project/spotify-bulk-actions-mcp
mcp.so	mcp.so/server/spotify-bulk-actions-mcp
awesome-mcp-servers	PR #1541 (pending)

---

Projects I've Built With This

Project	Description	Links
recordOS	Which albums do you love most? A visual album collection app	Live · Repo
Festival Navigator	Navigate multi-day festivals with friends	Repo

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)

2. Clone & Setup

# 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:

python setup_auth.py

After login, your token is saved locally in .spotify_cache/.

4. Test It Works

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):

{
  "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:

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:

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!