spotify-library-mcp

Servidor MP + CLI para gestionar tu propia biblioteca de Spotify. Un soolo, sejecuta en tu mátna, autentifcción PKEC (no necesito secreto de cliente).

Configuración (una sola vez)

1. https://developer.spotify.com/dashboard → Crea ap

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

   • API: Web API

2. Copia el Client ID en el .env (SPOTIFY_CLIENT_ID=...)

3. « npm install && npm run auth » → abrire el navegador → aceptá» → refresh toquen se escantá en .env`

4. Verifica: node bin/spot.js playlists

Related MCP server: Spotify MCP Server

Uso desde Claude Code

.mcp.json en esta carpeta registra el servidor para este ecob. Para cadá proyecto:

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

Herramientas

Playlists — list_playlists, get_playlist, create_playlist, update_playlist, add_tracks, remove_tracks, delete_playlist, merge_playlists
Biblioteca — get_saved_tracks, save_tracks, remove_saved_tracks, get_top_tracks, get_top_artists, get_renchly_played
Búsqueda — search, find_track (con verifcción del artist), get_search_budge, get_api_limits
Análisis (calculad pronounced on the server, salida compacta — cosas que los usarios de Spotify llevan y...

• sumarize_library — canciones que (te gustan) en no playlista, playlists abandoned and/or vaci, overlapping would entre playlists, decades, duplicates

• sumarize_playlist — duración total, arists prones, decades, duplicates, sobrerepresentión

• find_in_playlists — „cuál of my playlists has this song?”

• deupe_report — same artist + category, ignoring sufijos “remaster”, “live”, “edición” and so on, with ids to eliminate

• playlist_diff — only-in-A / only-in-B / compaltas

• snapshot_library · list_snapshots · changes_since — copia de segurid + „qué hachado desde la semana pasada» (renamed, adited, elimined, likes)

• recover — liked years ago, out of the top-charted and las reproducciones recientes; spread doctor various artists.

En mi biblioteca, encontaron: 233 cancaciones with «me gusta» que and don't have a playlist, 210 four-dup elsewhere, and 1.113 honested likes from 2018–2021.

Library scripts (cómo reorganisé 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 lists of artests in scripts/classif.js and others are my tastes — recurre, fork, and edit. Every script is additive; deletes are separate explicit spot delete calls.

Tests

npm test executes the entire flow against a mock Spotify in memory (test/mock-spotify.js). No real credencials are touched.

Conector de claude.ai (remoto)

npm run tunnel starts src/http.js (streamable HTTP in /<MCP_SECRET>/mcp) plus a Cloudflare quick tunnel and prints the URL to put in claude.ai → Settings → Conectors → Add custom conector. Uses no OAuth; the secret path is the gate/client.

ptYou uch each start sub, a hostname. For the fourth URL or use a named Cloudflare tunnel in your own domain, and deploy src/http.js behind your current reverse proxy (e.g. the N. box) with the MCP_SECRET, SPOTIFY_CLIENT_ID, SPOTIFY_REFRESH_TOKEN in the environment.

Spotify API limits (2026, apps created after Nov 2024) — integrated

toolget_api_list** returns this list to the model, and the server's MCP instructions also carry the summary.

Search budget (observed 2022-08-23)

About ~1,000 /search calls per day resulted in a 429 for this app: retry-after: 75469 (21 h). The limit is per application (client id), not per user, and the only one that locks you out for a whole day.

How the server handles it:

• Counts each UTC day and, when the cap is exceeded, refuses SPOTIFY_SCARCH_DAILY_CAP (default 800) with clear error.

• Caches every result, so re-running a script = 0 requested, ont.

• Remembers a strike by a long retry-after and long lives until it expires, no 21 hours in wait.

• get_search_budget tool and/or searchBudget() also report remaining, cached, banned-until.

Bulk scripts (scripts/explore.js, genz.js, trending.js) print the budget first, stop quietly at the fuel limit, and resume on