spotify-library-mcp

Lokaler MCP-Server + CLI zur Verwaltung deiner eigenen Spotify-Bibliothek. Einzelbenutzer, läuft auf deinem Rechner, PKCE-Auth (kein Client-Secret nötig).

Einrichtung (einmalig)

1. https://developer.spotify.com/dashboard → Create app

   • Redirect URI: http://127.0.0.1:8888/callback

   • API: Web API

2. Kopiere die Client-ID in .env (SPOTIFY_CLIENT_ID=...)

3. npm install && npm run auth → der Browser öffnet sich → bestätigen → Refresh-Token wird in .env geschrieben

4. Überprüfen: node bin/spot.js playlists

Related MCP server: Spotify MCP Server

Verwendung mit Claude Code

.mcp.json in diesem Projektordner registriert den Server für dieses Projekt. Für jedes Projekt:

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

Werkzeuge

Playlists — list_playlists, get_playlist, create_playlist, update_playlist, add_tracks, remove_tracks, delete_playlist, merge_playlists Bibliothek — get_saved_tracks, save_tracks, remove_saved_tracks, get_top_tracks, get_top_artists, get_recently_played Suche — search, find_track (artist-verified), get_search_budget, get_api_limits Analyse (serverseitig berechnet, kompakte Ausgabe — Dinge, die Spotify-Nutzer seit einem Jahrzehnt fordern):

• summarize_library — gemerkte Songs in keiner Playlist, veraltete/leere Playlists, Überschneidungen zwischen Playlists, Jahrzehnte, Duplikate

• summarize_playlist — Laufzeit, Top-Interpreten, Jahrzehnte, Duplikate, Überreprésentation

• find_in_playlists — „In welchein meiner Playlists steckt dieser Song?"

• dedupe_report — gleicher Interpret in gleicher Titl, Remaster/Live/Edit-Suffixe ignoriert, mit zu entfernenden IDs

• playlists_diff — nur-in-A / nur-in-B / geteilt

• snapshot_library · list_snapshots · changes_since — Backup + „was geänderte seit letzter Woche" (Umbenennungen, Hinzugefügtes, Entferntes, Likes)

• rediscoverer — vor Jahren geliebt, aber nicht in Top-Tracks und letzten Plays; über Interpreten verteilt

Bei meiner Bibliothek fanden diese Werkzeuge: 233 gemerkte Songs in keiner Playlist, 210 Fast-Duplikate innerhalb von Playlists, 1.113 vergessene Likes aus 2018–2021.

Bibliotheksskripte (wie ich 40 Playlists → 9 reorganisiert habe)

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

Die Künstlerlisten in scripts/classify.js und Verwandten sind mein Geschmack — forken und anpassen. Jedes Skript ist additiv; Löschungen erfolgen über separate, explizite spot delete-Aufrufe.

Tests

npm test lässt den gesamten Ablauf gegen einen In-Memory-Mock-Spotify (src/mock-spotify.js) laufen. Es werden keine echten Anmeldedaten angefasst.

claude.ai-Connector (remote)

npm run tunnel startet src/http.js (Streamable HTTP unter /<MCP_SECRET>/mcp) sowie einen Cloudflare-Quick-Tunnel und gibt die URL aus, die du in claude.ai → Settings → Connectors → Custom connector hinzufügen einfügst (kein OAuth; der geheime Pfad ist das Tor).

Quick-Tunnel erhalten bei jedem Start einen neuen Hostnamen. Für eine stabile URL betreibe einen benannten Cloudflare-Tunnel auf deiner eigenen Domain oder deploye src/http.js hinter deinem vorhandenen Reverse-Proxy (z. B. der Nightscout-Box) mit MCP_SECRET, SPOTIFY_CLIENT_ID, SPOTIFY_REFRESH_TOKEN in der Umgebung.

Spotify-API-Limits (2026, Apps nach Nov. 2024 erstellt) — eingebaut

Das get_api_limits-Werkzeug gibt diese Liste an das Modell zurück; die MCP-Anweisungen des Servers enthalten ebenfalls die Zusammenfassung.

Suchbudget (ermittelt am 2026-08-23)

~1.000 /search-Aufrufe an einem Tag brachten dieser App ein 429 mit retry-after: 75469 (21 h). Das Limit ist pro App (Client-ID), nicht pro Benutzer, und es ist die einzige Kontingent, die wir erreicht haben, die für einen Tag aussperrt.

Was der Server dagegen tut (src/budget.js, Zustand in .search-budget.json):

• zählt Suchen pro UTC-Tag und lehnt Anfragen über SPOTIFY_SEARCH_DAILY_CAP (Standard: 800) mit klarer Fehlermeldung ab

• cached jedes Suchergebnis, sodass erneute Skriptläufe 0 Suchen kosten

• speichert einen Bann aus einem langen retry-after ab und schlägt schnell fehl, bis er abläuft — keine 21-stündigen Schlafphasen

• get_search_budget-Tool / searchBudget() melden verbleichende, gecachte und gebannt-bis

Bulk-Skripte (scripts/explore.js, genz.js, trending.js) geben zuerst das Budget aus, stoppen sauber am Limit und setzen beim Neutern fort (sie überspringene, was bereits in der Playlist ist). Plantalen ≈ 250 Suche pro Skript pro Tag oder verwende eine zweite Spotify-App für Unmassgeschäfte.

Morgenplan: Bann endet 2026-08-24 ~14:00 IDT → explore ausführen (≈400, zwei Tage) oder eine frische Client-ID darauf zeigen.