spotify-library-mcp

나만의 Spotify 라이브러리를 관리하는 로컬 MCP 서버 + CLI. 단일 사용자, 로컬 머신에서 실행, PKCE 인증 (클라이언트 시크릿 불필요).

설정 (1회용)

1. https://developer.spotify.com/dashboard → 앱 만들기

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

   • API 유형: Web API

2. Client ID를 .env에 복사하세요 (SPOTIFY_CLIENT_ID=...)

3. npm install && npm run auth → 브라우저가 열림 → 승인 → 리프레시 토큰이 .env에 기록됨

4. 확인: node bin/spot.js playlists

Related MCP server: Spotify MCP Server

Claude Code에서 사용

이 폴더에 있는 .mcp.json이 이 프로젝트에 서버를 등록합니다. 모든 프로젝트에서:

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

도구

플레이리스트 — list_playlists, get_playlist, create_playlist, update_playlist, add_tracks, remove_tracks, delete_playlist, merge_playlists ** 라이브러리** — get_saved_tracks, save_tracks, remove_saved_tracks, get_top_tracks, get_top_artists, get_recently_played 검색 — search, find_track (아티스트 검증됨), get_search_budget, get_api_limits 분석 (서버 측에서 계산, 간결한 출력 — Spotify 사용자들이 10년 동안 요청해 온 기능):

• summarize_library — 플레이리스트에 없는 좋아요 곡, 오래되었거나 비어 있는 플레이리스트, 플레이리스트 간 중복, 연대별 분포, 중복 곡

• summarize_playlist — 러닝타임, 상위 아티스트, 연대, 중복, 과잉 편중

• find_in_playlists — "이 노래가 내 플레이리스트 중 어디에 있지?"

• dedupe_report — remaster/live/edit 접미사를 무시하고 아티스트+제목이 같은 중복 목록, 삭제할 id 포함

• playlist_diff — A에만 있음 / B에만 있음 / 공통

• snapshot_library · list_snapshots · changes_since — 백업 + "지난주 이후 변경 사항" (이름 변경, 추가, 삭제, 좋아요)

• rediscover — 몇 년 전에 좋아요한 곡 중 상위 트랙과 최근 재생 기록에 없는 곡. 아티스트별로 분산

실제 라이브러리에서 발견한 것: 플레이리스트에 없는 좋아요 곡 233개, 플레이리스트 안 거의 중복 210건, 2018–2021년의 잊힌 좋아요 1,113건.

라이브러리 스크립트 (플레이리스트 40개를 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

scripts/classify.js 등에 있는 아티스트 목록은 제 취향입니다 — 포크해서 수정하세요. 모든 스크립트는 기본적으로 추가만 수행하며, 삭제는 별도로 명시적인 spot delete 호출로 처리합니다.

테스트

npm test는 인메모리 mock Spotify(test/mock-spotify.js)로 전체 흐름을 테스트합니다. 실제 인증 정보는 사용하지 않습니다.

claude.ai 커넥터 (원격)

npm run tunnel은 src/http.js (/<MCP_SECRET>/mcp의 Streamable HTTP)를 실행하고 Cloudflare quick tunnel을 함께 시작하여, claude.ai → Settings → Connectors → Add custom connector에 붙여넣을 URL을 출력합니다 (OAuth 없음, secret 경로가 게이트 역할).

Quick tunnel은 시작할 때마다 새 호스트네임을 받습니다. 안정적인 URL이 필요하면 본인 도메인에 named Cloudflare tunnel을 실행하거나, 기존 리버스 프록시(예: Nightscout 상자) 뒤에 src/http.js를 배포하고 환경 변수에 MCP_SECRET, SPOTIFY_CLIENT_ID, SPOTIFY_REFRESH_TOKEN을 설정하세요.

Spotify API 제한 (2026, 2024년 11월 이후 생성된 앱) — 내장됨

get_api_limits 도구는 이 목록을 모델에 반환합니다. 서버의 MCP instructions에도 요약이 포함됩니다.

검색 예산 (2026-08-23 확정 정보)

하루에 ~1,000회의 SEARCH 호출만으로 retry-after: 75469 (21시간)에 대한 429가 발생했습니다. 이 제한은 앱(클라이언트 id)별이며, 사용자별이 아니라 하루 라이브러 기준 중 유일하게 일일 락이 걸리는 할당량입니다.

서버가 이를 처리하는 방법 (src/budget.js, 상태는 .search-budget.json):

• UTC 시간 기준으로 검색량을 세고 SPOTIFY_SEARCH_DAILY_CAP 기본 800 초과 시 명확한 오류를 반환합니다.

• 모든 검색 결과를 캐시하므로, 재실행 시 검색량은 0입니다.

• 긴 retry-after에서 발생한 차단을 기억하고, 만료될 때까지 빠르게 실패합니다. — 21시간 대기 없음.

• get_search_budget 도구 / search_chunk / report remaining, cached, banned-until.

대량 스크립트 (scripts/explore.js, genz.js, trending.js)는 먼저 예산을 출력하고, 한도에서 깔끔히 멈추며, 재실행 시 이어서 진행합니다 (이미 플리스트에 있는 것은 건너뜁니다). 스크립트별 하루 약 250개의 검색을 계획하거나, 대량 작업은 둘째 Spotify 앱을 사용하세요.

내일 계획: 차단 해제 2026-08-24 약~14:00 IDT → 그 후 validator 실행 (≈400, 두 날) 또는 새 client id를 지정.