io.github.khglynn/spotify-bulk-actions-mcp
Allows batch playlist creation, library exports, and large-scale library management with confidence scoring for track matching and human-in-the-loop review.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@io.github.khglynn/spotify-bulk-actions-mcp import CSV of podcast songs and create playlist"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: Tempo
Listed On
Directory | Link |
PyPI | |
mcp.so | |
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 | |
Festival Navigator | Navigate multi-day festivals with friends |
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_SECRETAlso on PyPI:
pip install spotify-bulk-actions-mcp- but you'll still need local.envand auth setup.
3. Authenticate with Spotify (One-Time)
This opens a browser for you to log in:
python setup_auth.pyAfter 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 |
| Verify Spotify auth is working |
| Get all artists you follow |
| Get all your liked songs |
| Artists from saved songs, ranked by count |
| Albums with N+ saved songs |
| Complete library export |
Listening Insights
Tool | Description |
| Your top artists (short/medium/long term) |
| Your top tracks (short/medium/long term) |
| Recently played tracks |
Bulk Library Actions
Tool | Description |
| Follow artists in bulk |
| Unfollow artists in bulk |
| Like/save tracks in bulk |
| Un-like tracks in bulk |
Search
Tool | Description |
| Search for a single track |
| Broader search when exact fails |
| Search many tracks with confidence scores |
| Get 30-second preview URL |
Playlist Creation
Tool | Description |
| Create a new playlist |
| Add tracks to existing playlist |
| Full CSV → playlist workflow |
| Create from batch search |
| Add reviewed/corrected tracks |
Playlist Management
Tool | Description |
| Get playlist details |
| Update name, description, public status |
| Get all tracks in a playlist |
| Export a playlist to CSV |
| Shared vs unique tracks between two playlists |
| Find duplicates in a playlist |
| Remove duplicates, keeping first occurrence |
| Bulk remove specific tracks |
| Move tracks within a playlist |
Utilities
Tool | Description |
| Validate a song 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
Create a CSV file:
title,artist
Bohemian Rhapsody,Queen
Hotel California,Eagles
Billie Jean,Michael JacksonAsk Claude:
"Create a playlist called 'My Mix' from this CSV: [paste CSV]"
Claude will:
Parse the CSV
Search each song with confidence scoring
Create the playlist with high-confidence matches
Show you uncertain matches to review
Bulk Podcast Playlist
For large lists (500+ songs):
Ask Claude to use
batch_search_trackswith your song listReview the results (HIGH goes in automatically)
Use
export_review_csvto get uncertain matchesReview/correct in a spreadsheet
Use
add_reviewed_tracksto 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 |
| Your Spotify credentials (gitignored) |
| Auth tokens and cached data (gitignored) |
| Main MCP server |
| Tool implementations |
Troubleshooting
"Not authenticated" error:
python setup_auth.pyRate 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
.envor token filesIf 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!
Available Tools
33 toolsadd_reviewed_tracksA
Add tracks from a reviewed CSV to an existing playlist.
Use this after reviewing uncertain matches from a batch search.
The CSV should have an 'action' column:
'approve': Add the matched track
'reject': Skip this track
spotify:track:xxx: Use this specific URI instead
Inputs: playlist_id (required), reviewed_csv (required). Returns: object
add_tracks_to_playlistA
Add tracks to an existing playlist.
Handles batching automatically (Spotify max 100 per request).
Inputs: playlist_id (required), track_uris (required). Returns: object
batch_search_tracksA
Search for multiple tracks with confidence scoring.
Categorizes results:
HIGH (>= 90%): Safe to auto-add
MEDIUM (70-89%): Should review
LOW (< 70%): Needs attention
NOT FOUND: No results
Inputs: songs (required), delay_seconds. Returns: object
check_auth_statusA
Check if Spotify authentication is set up and working.
Returns current user info if authenticated.
Inputs: no named parameters. Returns: object
compare_playlistsB
Compare two playlists to find shared and unique tracks.
Inputs: playlist_id_1 (required), playlist_id_2 (required). Returns: object
create_playlistC
Create a new Spotify playlist.
Inputs: name (required), description, public. Returns: object
create_playlist_from_search_resultsB
Create a playlist from batch search results.
Inputs: name (required), batch_results (required), include_confidence, description, +1 more. Returns: object
export_library_summaryA
Export a complete summary of your Spotify library.
Includes:
Followed artists
Top artists by saved song count
Albums with most saved songs
Inputs: use_cache. Returns: object
export_playlist_to_csvA
Export a playlist to CSV format.
Great for backing up playlists or sharing song lists.
Inputs: playlist_id (required). Returns: object
export_review_csvA
Export medium/low confidence matches to a CSV for human review.
Inputs: batch_results (required). Returns: object
find_duplicate_tracksB
Find duplicate tracks in a playlist.
Inputs: playlist_id (required). Returns: object
follow_artistsB
Follow artists on Spotify.
Inputs: artist_ids (required). Returns: object
get_albums_by_song_countA
Find albums where you have N or more saved songs.
Great for finding albums worth buying on vinyl!
Inputs: min_songs, use_cache. Returns: object
get_followed_artistsB
Get all artists you follow on Spotify.
Inputs: use_cache. Returns: object
get_library_artistsA
Get unique artists from your saved songs, sorted by song count.
This shows artists you have saved songs from (even if not followed), ranked by how many songs you've saved.
Inputs: use_cache. Returns: object
get_playlist_infoC
Get information about a playlist.
Inputs: playlist_id (required). Returns: object
get_playlist_tracksA
Get all tracks from a playlist.
Inputs: playlist_id (required). Returns: object
get_recently_playedC
Get your recently played tracks.
Inputs: limit. Returns: object
get_saved_tracksA
Get all your liked/saved songs on Spotify.
Note: This may take 1-2 minutes for large libraries (10k songs).
Inputs: use_cache. Returns: object
get_top_artistsA
Get your top artists based on listening history.
Great for understanding your music taste and finding festival lineups.
Inputs: time_range, limit. Returns: object
get_top_tracksA
Get your top tracks based on listening history.
Inputs: time_range, limit. Returns: object
get_track_preview_urlA
Get the 30-second preview URL for a track.
Inputs: track_uri (required). Returns: object
import_and_create_playlistA
Full workflow: Parse song list CSV, search all tracks, create playlist.
This is the main tool for bulk playlist creation from a list of songs.
Inputs: name (required), csv_content (required), include_confidence, description, +1 more. Returns: object
parse_song_list_csvA
Parse a CSV of songs into a structured list.
Use this to validate your CSV before batch searching.
Inputs: csv_content (required). Returns: object
remove_duplicate_tracksA
Remove duplicate tracks from a playlist, keeping the first occurrence.
For safety, returns a preview unless confirm=True.
Inputs: playlist_id (required), confirm. Returns: object
remove_tracks_from_playlistA
Remove specific tracks from a playlist.
For safety, returns a preview unless confirm=True.
Inputs: playlist_id (required), track_uris (required), confirm. Returns: object
reorder_playlist_tracksC
Move tracks within a playlist.
Inputs: playlist_id (required), range_start (required), insert_before (required), range_length. Returns: object
save_tracksA
Save tracks to your Spotify library (like/heart them).
Inputs: track_ids (required). Returns: object
search_trackC
Search for a single track and get matches with confidence scores.
Inputs: title (required), artist (required), limit. Returns: object
search_track_fuzzyA
Broader fuzzy search when exact match fails.
Tries multiple strategies:
Exact title + artist
Title only
Simplified title (removing parentheses, etc.)
Inputs: title (required), artist (required), limit. Returns: object
unfollow_artistsA
Unfollow artists on Spotify.
For safety, returns a preview unless confirm=True.
Inputs: artist_ids (required), confirm. Returns: object
unsave_tracksA
Remove tracks from your Spotify library.
For safety, returns a preview unless confirm=True.
Inputs: track_ids (required), confirm. Returns: object
update_playlistB
Update playlist details (name, description, public status).
Only provide the fields you want to change.
Inputs: playlist_id (required), name, description, public. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 33 tools
Each tool has a clearly defined purpose, with distinct boundaries between batch search, single search, fuzzy search, and playlist operations. The descriptions provide clear differentiation, even for similar tools like batch_search_tracks and search_track.
All tool names follow a consistent verb_noun pattern, using underscores and descriptive verbs. There are no mixed conventions or vague names, making the toolset predictable for an agent.
With 33 tools, the count is high but justified by the comprehensive scope of bulk Spotify operations, including search, playlist management, library actions, and CSV workflows. It is slightly above the typical range but each tool serves a distinct purpose.
The tool set covers the full lifecycle of bulk actions: authentication, search with confidence scoring, playlist creation and modification, duplicate management, library operations, and CSV import/export. No obvious gaps are present for the stated purpose.
Maintenance
Related MCP Connectors
Spotify MCP — Web API via client_credentials OAuth
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
One MCP server for all web data. Scrape, search, crawl, and AI research in one install.
Related MCP Servers
- AlicenseBqualityDmaintenanceAn MCP server that enables users to control Spotify playback, search music, and manage playlists through natural conversation. It is updated for the February 2026 Spotify Web API changes and supports full playlist CRUD operations.68MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server for Spotify control and synchronized lyrics retrieval that enables playback management, queue navigation, and music search capabilities. It also features perception tools for real-time track analysis, including BPM, key detection, and timestamped lyrics.72 npm3Apache 2.0
- AlicenseNot gradedqualityFmaintenanceAn MCP server that enables users to control Spotify playback, search for music, and manage playlists through MCP-compatible clients. It supports features like track recommendations and playback management using secure OAuth authentication.MIT
- AlicenseNot gradedqualityDmaintenanceA remote MCP server for Spotify with brokered OAuth and server-side intelligence, enabling search, playlist management, playback control, library analysis, and listening trends via natural language.127 npm4MIT