spotify-library-mcp
Manages your own Spotify library: playlists, saved tracks, top tracks/artists, search, library analysis (summaries, duplicates, playlist diffs, snapshots, rediscovery), with Spotify PKCE auth and API quota handling.
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., "@spotify-library-mcp Merge my Chill and Focus playlists into one called Study, then delete the old ones."
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-library-mcp
Local MCP server + CLI for managing your own Spotify library. Single user, runs on your machine, PKCE auth (no client secret needed).
Setup (one time)
https://developer.spotify.com/dashboard → Create app
Redirect URI:
http://127.0.0.1:8888/callbackAPI: Web API
Copy the Client ID into
.env(SPOTIFY_CLIENT_ID=...)npm install && npm run auth→ browser opens → approve → refresh token is written to.envVerify:
node bin/spot.js playlists
Related MCP server: Spotify MCP Server
Use from Claude Code
.mcp.json in this folder registers the server for this project. For every project:
claude mcp add --scope user spotify-library -- node /path/to/spotify-library-mcp/src/server.jsCLI
node bin/spot.js playlists
node bin/spot.js playlist <id>
node bin/spot.js rename <id> "New name"
node bin/spot.js merge '{"sourceIds":["a","b"],"newName":"Merged","deleteSources":true}'
node bin/spot.js delete <id>
node bin/spot.js top short_term 20
node bin/spot.js summary # whole library
node bin/spot.js summary <id> # one playlist
node bin/spot.js find "Sultans" # which playlists contain it
node bin/spot.js dupes
node bin/spot.js diff <a> <b>
node bin/spot.js snapshot weekly && node bin/spot.js changes
node bin/spot.js rediscover 4 50Tools
Playlists — list_playlists, get_playlist, create_playlist, update_playlist, add_tracks, remove_tracks, delete_playlist, merge_playlists Library — get_saved_tracks, save_tracks, remove_saved_tracks, get_top_tracks, get_top_artists, get_recently_played Search — search, find_track (artist-verified), get_search_budget, get_api_limits Analysis (computed server-side, compact output — things Spotify users have asked for for a decade):
summarize_library— liked songs in no playlist, stale/empty playlists, cross-playlist overlaps, decades, dupessummarize_playlist— runtime, top artists, decades, duplicates, over-representationfind_in_playlists— "which of my playlists has this song?"dedupe_report— same artist+title ignoring remaster/live/edit suffixes, with ids to removeplaylist_diff— only-in-A / only-in-B / sharedsnapshot_library·list_snapshots·changes_since— backup + "what changed since last week" (renames, adds, removes, likes)rediscover— liked years ago, absent from top tracks and recent plays; spread across artists
On my library these found: 233 liked songs in no playlist, 210 near-duplicates inside playlists, 1,113 forgotten likes from 2018–2021.
Library scripts (how I reorganised 40 playlists → 9)
node scripts/pull.js library.json # snapshot playlists + likes + tops
node scripts/build.js library.json # file every track into genre collections (additive)
node scripts/moods.js # collapse genre collections into mood playlists
node scripts/curate.js library.json # like picks, build Programming + שישי
node scripts/nostalgia.js library.json # 3-generation nostalgia
node scripts/explore.js library.json # 🧭 Explore: ~400 new artists, many languages (search-heavy, resumable)
node scripts/genz.js # 🚗 Gen Z
node scripts/trending.js library.json # 📈 Trending from live popularityThe artist lists in scripts/classify.js and friends are my taste — fork and edit. Every script is additive; deletions are separate explicit spot delete calls.
Tests
npm test runs the whole flow against an in-memory mock Spotify (test/mock-spotify.js). No real credentials touched.
claude.ai connector (remote)
npm run tunnel starts src/http.js (Streamable HTTP at /<MCP_SECRET>/mcp) plus a Cloudflare quick tunnel and prints the URL to paste into claude.ai → Settings → Connectors → Add custom connector (no OAuth; the secret path is the gate).
Quick tunnels get a new hostname each start. For a stable URL either run a named Cloudflare tunnel on your own domain, or deploy src/http.js behind your existing reverse proxy (e.g. the Nightscout box) with MCP_SECRET, SPOTIFY_CLIENT_ID, SPOTIFY_REFRESH_TOKEN in the environment.
Spotify API limits (2026, apps created after Nov 2024) — baked in
What | Status | Handled how |
| removed | client throws a clear error before any request |
batch | 403 | same; use single-item endpoints |
artist | gone | no genre data available, use your own knowledge |
| renamed | client uses new paths |
| deprecated |
|
| deprecated |
|
name-only search | returns karaoke/covers |
|
| ~1000/day per app → 429 with | persistent daily budget (default 800, |
~500 rapid calls | silent TLS-level drop for ~10 min (no 429) | 150 ms pacing + retry with backoff |
get_api_limits tool returns this list to the model; the server's MCP instructions carry the summary too.
Search budget (learned 2026-08-23)
~1,000 /search calls in one day got this app a 429 with retry-after: 75469 (21 h). The limit is per app (client id), not per user, and it's the only quota we've hit that locks you out for a day.
What the server does about it (src/budget.js, state in .search-budget.json):
counts searches per UTC day and refuses past
SPOTIFY_SEARCH_DAILY_CAP(default 800) with a clear errorcaches every search result, so reruns of a script cost 0 searches
remembers a ban from a long
retry-afterand fails fast until it expires — no 21-hour sleepsget_search_budgettool /searchBudget()report remaining, cached, banned-until
Bulk scripts (scripts/explore.js, genz.js, trending.js) print the budget first, stop cleanly at the cap, and resume on rerun (they skip what's already in the playlist). Plan ≈ 250 searches per script per day, or use a second Spotify app for bulk jobs.
Tomorrow's plan: ban lifts 2026-08-24 ~14:00 IDT → run explore (≈400, two days) or point a fresh client id at it.
Available Tools
27 toolsadd_tracksA
Add tracks (ids or spotify:track: URIs) to a playlist, skipping ones already present.
Inputs: track_ids (required), playlist_id (required).
changes_sinceA
What changed since a snapshot (default: latest): playlists created/deleted/renamed, tracks added/removed per playlist, likes added/removed.
Inputs: snapshot.
create_playlistC
Create a new playlist for the user.
Inputs: name (required), public, description.
dedupe_reportB
Duplicate tracks (same artist + title, ignoring remaster/edit suffixes) inside each playlist, with ids to remove.
Inputs: no named parameters.
delete_playlistA
Remove a playlist from the user's library (unfollow). Irreversible for owned playlists.
Inputs: playlist_id (required).
find_in_playlistsA
Which of the user's playlists contain a track (by name/artist substring, id, or uri); also whether it is Liked.
Inputs: query (required).
find_trackA
Find one track, verifying the artist is on the result (avoids karaoke/cover mismatches). Returns null if no verified match.
Inputs: track (required), artist (required).
get_api_limitsA
What this Spotify app can and cannot do (endpoints removed/renamed by Spotify for new apps).
Inputs: no named parameters.
get_playlistB
Get a playlist's details and its full track list.
Inputs: playlist_id (required).
get_recently_playedD
Recently played tracks.
Inputs: limit.
get_saved_tracksB
All tracks the user has Liked.
Inputs: no named parameters.
get_search_budgetA
Remaining /search calls for today, cache size, and whether a Spotify search ban is active. Check before bulk searching.
Inputs: no named parameters.
get_top_artistsC
The user's most-played artists.
Inputs: limit, time_range.
get_top_tracksC
The user's most-played tracks.
Inputs: limit, time_range.
list_playlistsA
List all playlists in the user's library (owned and followed).
Inputs: no named parameters.
list_snapshotsB
List saved snapshots.
Inputs: no named parameters.
merge_playlistsA
Merge several playlists into one (existing target or a new one), deduplicating tracks. Optionally delete sources.
Inputs: source_ids (required), new_name, target_id, delete_sources.
playlist_diffC
Tracks only in A, only in B, and shared count.
Inputs: playlist_a (required), playlist_b (required).
rediscoverB
Liked songs from years ago that no longer appear in top tracks or recent plays — forgotten favourites, spread across artists.
Inputs: limit, min_years_ago.
remove_saved_tracksC
Remove tracks from Liked Songs.
Inputs: track_ids (required).
remove_tracksC
Remove tracks from a playlist.
Inputs: track_ids (required), playlist_id (required).
save_tracksB
Add tracks to the user's Liked Songs.
Inputs: track_ids (required).
searchD
Search Spotify.
Inputs: query (required), type, limit.
snapshot_libraryA
Save a full snapshot of all playlists + liked songs to disk (backup; enables changes_since).
Inputs: label.
summarize_libraryA
Whole-library health: liked songs in no playlist, stale/empty playlists, cross-playlist overlaps, per-playlist counts, liked-songs stats. Use before any reorganisation.
Inputs: no named parameters.
summarize_playlistB
Stats for one playlist: runtime, top artists, decades, duplicates, over-representation.
Inputs: playlist_id (required).
update_playlistB
Rename a playlist or change its description/visibility.
Inputs: playlist_id (required), name, public, description.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 27 tools
Most tools have a clear resource-and-action boundary: playlist operations, Liked Songs operations, search, snapshots, and stats are generally easy to tell apart. A few pairs such as search/find_track and dedupe_report/summarize_playlist overlap conceptually, but the descriptions clarify their distinct purposes.
The dominant pattern is verb_noun: list_playlists, create_playlist, add_tracks, remove_saved_tracks, get_top_tracks. Minor outliers like playlist_diff, changes_since, and rediscover break the pattern slightly but do not make the set confusing.
27 tools is on the high side, and several reporting, snapshot, and utility tools overlap in broad purpose. The platform supports a wide library-management workflow, so most tools are defensible, but the set would benefit from some consolidation.
The set covers playlist CRUD, liked-songs management, search, library summaries, deduplication, backups, and listening history. Missing playlist operations like reordering tracks is a noticeable but non-critical gap; the core workflows do not dead-end.
Maintenance
Related MCP Connectors
Your versioned prompt library: search, read, save and version prompts from Claude Code.
Run UX research from Claude — create card sort studies, list studies, pull headline stats.
Notes, tasks, habits, journal and 6 more tools Claude can read and change, with undo. Free.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Related MCP Servers
- FlicenseDqualityDmaintenanceEnables Claude to interact with Spotify by searching songs, creating playlists, getting recommendations, and managing your music through your Spotify account.73-
- AlicenseNot gradedqualityNot gradedmaintenanceConnects Claude to Spotify for music discovery, playlist creation, and collection analysis through natural language. Enables searching songs, analyzing music diversity, creating playlists, and getting recommendations using Spotify's API.-
- AlicenseAqualityDmaintenanceIntegrates Spotify with Claude to enable voice-controlled music playback, playlist management, and personalized recommendations through conversational AI. It provides comprehensive tools for searching tracks, managing liked songs, and analyzing listening habits.151MIT
- AlicenseAqualityCmaintenanceEnables Claude to control Spotify playback, search tracks/albums/artists/playlists, and manage the queue via the Spotify API.6MIT