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)

1. https://developer.spotify.com/dashboard → Create app
   • Redirect URI: http://127.0.0.1:8888/callback
   • API: Web API
2. Copy the Client ID into .env (SPOTIFY_CLIENT_ID=...)
3. npm install && npm run auth → browser opens → approve → refresh token is written to .env
4. Verify: node bin/spot.js playlists

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.js

CLI

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 50

Tools

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, dupes
• summarize_playlist — runtime, top artists, decades, duplicates, over-representation
• find_in_playlists — "which of my playlists has this song?"
• dedupe_report — same artist+title ignoring remaster/live/edit suffixes, with ids to remove
• playlist_diff — only-in-A / only-in-B / shared
• snapshot_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 popularity

The 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
/audio-features, /recommendations, related-artists	removed	client throws a clear error before any request
batch GET /tracks?ids=, /artists?ids=	403	same; use single-item endpoints
artist genres field	gone	no genre data available, use your own knowledge
/playlists/{id}/tracks	renamed /items, entries under item	client uses new paths
POST /users/{id}/playlists	deprecated	POST /me/playlists
PUT/DELETE /me/tracks	deprecated	/me/library?uris= (max 20 per call, chunked)
name-only search	returns karaoke/covers	find_track tool verifies the artist
/search quota	~1000/day per app → 429 with retry-after ≈ 21h	persistent daily budget (default 800, SPOTIFY_SEARCH_DAILY_CAP), result cache, ban memory — see below
~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 error
• caches every search result, so reruns of a script cost 0 searches
• remembers a ban from a long retry-after and fails fast until it expires — no 21-hour sleeps
• get_search_budget tool / 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.