spotify-library-mcp

自分のSpotifyライブラリを管理するための、ローカルMCPサーバー＋CLI。シングルユーザーで、あなたのマシン上で動作し、PKCE認証を使用（クライアントシークレット不要）。

セットアップ（初回のみ）

1. https://developer.spotify.com/dashboard → アプリを作成

   • リダイレクトURI: http://127.0.0.1:8888/callback

   • API: Web API

2. クライアント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 は、インメモリのモックSpotify（test/mock-spotify.js）に対して全フローを実行します。実際の認証情報には一切触れません。

claude.aiコネクタ（リモート）

npm run tunnel は src/http.js（/<MCP_SECRET>/mcp でのStreamable HTTP）とCloudflareのクイックトンネルを起動し、claude.ai → Settings → Connectors → Add custom connector に貼り付けるURLを表示します（OAuth不要。シークレットパスがゲートになる）。

クイックトンネルは起動のたびに新しいホスト名になります。安定したURLが必要な場合は、自分のドメインで名前付きCloudflareトンネルを実行するか、既存のリバースプロキシ（例: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日に約1,000回の /search 呼び出しで、このアプリは retry-after: 75469（21時間）付きの 429 を受けました。制限はアプリ（クライアントID）ごとであり、ユーザーごとではありません。また、丸1日ロックアウトされるのは、これまでに当たったクォータの中で、この一つだけです。

サーバーが行う対処（src/budget.js、状態は .search-budget.json）:

• UTC日ごとに検索数をカウントし、SPOTIFY_SEARCH_DAILY_CAP（既定800）を超えたら明確なエラーで拒否する

• すべての検索結果をキャッシュするので、スクリプトを再実行しても検索数は消費しない

• 長い retry-after による禁止状態を記憶し、期限が切れるまで早めに失敗する — 21時間待ちしない

• get_search_budget ツール / searchBudget() が、残数・キャッシュの有無・禁止解除時刻（banned-until）を報告する

一括スクリプト（scripts/explore.js、genz.js、trending.js）は、まずバジェットを表示し、限度に達したらきれいに停止し、再実行時に再開します（すでにプレイリストにあるものはスキップします）。スクリプトあたり1日約250回の検索で見積もってください。一括ジョブには別のSpotifyアプリを使いましょう。

明日の予定: 2026-08-24 の14:00 IDTごろに禁止が解除 → explore（約400件、2日分）を実行するか、新しいクライアントIDをそれに向ける。