Spotify MCP

SpotifyMCP

Spotify Web API の MCP サーバーです。再生、ライブラリ、プレイリスト、検索、ポッドキャストに対応しています。Spotify とは提携していません。

Spotify Web API の幅広いツールを提供し、他の多くのサーバーが省略している機能も備えています。登録が必要なラッパーについても、隠さず説明しています。生成された一覧は、登録が必要なエンドポイントをご覧ください。

デフォルトで利用できるものと、それ以外の設定方法。 環境変数を設定せずにサーバーを起動すると、検索、再生、プレイリスト、ライブラリ、フォロー機能を含む、厳選されたツール群が登録されます。これは、何も入力する前にツール一覧がコンテキストウィンドウを占有しないように調整されています。SPOTIFY_MCP_TOOLSETS=all を設定するとレジストリ全体が登録され、stats.fm ツールは SPOTIFY_MCP_STATSFM=1 でオプトインできます。どちらも docs/configuration.md にある1行の設定で利用できます。

SPOTIFY_MCP_TOOLSETS を設定せずにサーバーを起動すると、131 個のツール（スキーマは150,111バイト）が登録されます。これは厳選されたデフォルトのツール群です（#889）。SPOTIFY_MCP_TOOLSETS=all を設定すると、562 個のツールに加えて、17 個の固定リソース、28 個のリソーステンプレート、14 個のプロンプトが登録されます。ツールセットと本番環境向けゲートによって、設定済みのホストでさらに絞り込めます。どちらの数値も、ファイナライザー適用後の実際の本番環境の tools/list を示しています。

3.0 以降

3.0 は、未解決の Issue がゼロになったリリースです — すべてのエピック、その配下のすべての Issue、自分たちで監査して見つけたすべての矛盾を解消しました。バックログの大部分は、クラッシュを引き起こすような意味での「バグ」ではありませんでした。このサーバーが、実際には確認していない値を報告していた箇所です。それこそが、本当に危険な誤りです。

また、2026 年 2 月に Spotify がその下位のエンドポイントを削除したため、ツールも削除しました。アーティストのフォロー機能も含まれており、こちらには移行先がまったくありません。

→ 3.0 のロードマップを読む

🤖 これをエージェントに貼り付けてください

以下のブロックを Claude Code、Cursor、OpenClaw、または任意のコーディングエージェントにコピーしてください。SpotifyMCP をセットアップしてくれます。

⚠️ Spotify の認証情報をチャットに貼り付けないでください。 Spotify の Developer Terms では、Client ID は認証情報として扱われます。§VI.1.1 では「I.D.s, client I.D.s, keys, passwords, security codes, or tokens」をまとめて Security Codes と定義し、§VI.1.3 では第三者への開示を禁じ、§VI.1.4 ではそれらの機密保持について利用者が責任を負うと定めています。会話に入力した情報は、モデルプロバイダーによって保持され、シェルの履歴に書き込まれ、エージェントのコンテキストウィンドウに取り込まれます。このサーバーが必要とする認証情報は Client ID だけですが、公開識別子ではなく Security Code です。パスワードと同じように扱ってください。

https://github.com/NovaLux12/spotify-mcp-server から Spotify MCP サーバーをセットアップしてください。

1. https://developer.spotify.com/dashboard で Spotify アプリを作成する手順を案内してください。
   リダイレクト URI は http://127.0.0.1:8888/callback にします。ダッシュボードの
   どこに Client ID が表示されるかを示したら、そこで止めてください。自分でコピーします。
2. クローンしてビルドします。
   git clone https://github.com/NovaLux12/spotify-mcp-server.git
   cd spotify-mcp-server && npm ci && npm run build
3. MCP ホストがサーバー環境変数を読み込むファイルを教えてください。ホストのサーバー
   設定は常に動作します。ローカルの .env が読み込まれるのは、このリポジトリの
   npm run dev または npm start 経由で起動した場合のみです。これらのコマンドは
   Node >=22.9 で --env-file-if-exists を渡します。公開済みのバイナリは読み込みません。
   追加する正確な行を表示してください。Client ID は自分で入力します。尋ねたり、
   入力した ID をそのまま表示したりしないでください。
4. サーバーを起動して認証コマンドを実行し、ブラウザーが開いたらログインを完了してください。
   このサーバーは PKCE を使用するため、クライアントシークレットは不要です。Client ID 以外に
   取得が必要な認証情報もありません。
5. 読み取り専用の spotify_doctor ツールで検証し、その結果の行を報告してください。

---

この MCP サーバーを選ぶ理由

クイックスタート

1. Spotify アプリを作成する

Spotify Developer Dashboard → アプリを作成 → 次のリダイレクト URI を正確に追加します：

http://127.0.0.1:8888/callback

Client ID をコピーします。

2. 認証する

SPOTIFY_CLIENT_ID=your_client_id_here npx -y @novalux12/spotify-mcp@latest auth

ブラウザーが開き、トークンが ~/.spotify-mcp/tokens.json に保存されます。以後、トークンは自動的に更新されます。

set SPOTIFY_CLIENT_ID=your_client_id_here && npx -y @novalux12/spotify-mcp@latest auth

$env:SPOTIFY_CLIENT_ID="your_client_id_here"; npx -y @novalux12/spotify-mcp@latest auth

SPOTIFY_HEADLESS=1 SPOTIFY_CLIENT_ID=your_client_id_here npx -y @novalux12/spotify-mcp@latest auth
# prints a URL → open it on any machine → paste the redirect back

3. MCP ホストに追加する

{
  "mcpServers": {
    "spotify": {
      "command": "npx",
      "args": ["-y", "@novalux12/spotify-mcp@latest"],
      "env": { "SPOTIFY_CLIENT_ID": "your_client_id_here" }
    }
  }
}

ホストを再起動します。チャット入力欄にハンマーのアイコンが表示されれば接続済みです。

claude mcp add spotify -- npx -y @novalux12/spotify-mcp@latest
export SPOTIFY_CLIENT_ID=your_client_id_here

"spotify": {
  "command": "node",
  "args": ["/path/to/spotify-mcp-server/dist/index.js"],
  "cwd": "/path/to/spotify-mcp-server",
  "env": { "SPOTIFY_CLIENT_ID": "your_client_id_here" }
}

できること

• 「今月のトップトラックは？」
• 「深夜のドライブ用プレイリストを作って」
• 「Blinding Lights をワークアウト用プレイリストに追加して」
• 「新しいエピソードが配信されたポッドキャストは？」
• 「すべてのプレイリストから重複を整理して」
• 「自分の好みはどんな感じ？それをもとにプレイリストを作って」
• 「stats.fm の生涯ジャンルと、今月再生したジャンルは一致している？」

設定

すべて環境変数で設定します。設定ファイルはありません。必須なのは SPOTIFY_CLIENT_ID のみです。

詳細なリファレンス：docs/configuration.md

spotify_doctor（CLI およびサーバー内ツール）は、追加設定なしで、トークンの状態、スコープの不足、Premium による制限、レート制限のクールダウン、リクエスト／クォータの使用状況（累積数とローリングウィンドウ内の数、#904）、読み取りキャッシュの負荷（保持中のエントリ数、保持バイト数、キャッシュには大きすぎるレスポンス、#894）を診断します。

2.0 へのアップグレード

2.0 は契約上のリリースです。ツール名が 1 つ廃止され、4 つの項目が移動し、1 つの保証が強化されました。

0. get_show_episodes は削除されました。 list_show_episodes を使用してください（同じエンドポイント、同じ引数で、ずれていた別名だけがなくなっています）。名前が変更されたのはこれだけで、インターフェース上のほかのすべての名前はそのままです。正確な登録数はこのファイルの先頭に自動生成されるため、数が古くならないよう、この文ではあえて独自の数を記載していません。

1. 破壊的な書き込みはフェイルクローズになります。 確認が必要な一括書き込みはすべて、クライアントで確認を求められない場合、確認なしに進めず拒否するようになりました。archive_played_episodes の confirm: true では、削除が承認されなくなりました（引き続き受け付けられますが、すべての結果で無視されたことが示されます）。ヘッドレス自動化では、SPOTIFY_MCP_CONFIRM=never を明示的に設定してください。

2. プレイリストの集合演算では、入力が正規化されています。 A/B ペアは playlist_a/playlist_b、順序付きリストは playlists、playlist_subtract では基準となるプレイリストに base_playlist_id を使用します。これが 2.0 の契約であり、併用が認められていた古い表記は 3.0 で廃止されました（#1287）。それらはどのツールのスキーマにも含まれなくなりました。引き続き古い表記を送信する呼び出しは、Spotify へのリクエスト前に拒否され、送信された値と代わりに送る値の両方を示す validation エラーが返されます。その reason は retired_input です。各ツールで宣言されていたエイリアスのペアまたはリストは 1 つだけなので、以下の表は一括ではなくツールごとの移行マップです。

   種類	正規名	そのツールで以前宣言されていた表記
   A/B ペア	playlist_a, playlist_b	a/b、または playlist_id_a/playlist_id_b、または playlist_a_id/playlist_b_id — ツールごとにいずれか 1 つ
   順序付きリスト	playlists	playlist_ids、または source_playlist_ids、または sources — ツールごとにいずれか 1 つ
   減算	base_playlist_id + playlists	subtract_playlist_ids、または位置指定形式の playlists: [base, ...sources] — ツールごとにいずれか 1 つ

   位置指定形式がなくなったため、省略できる基準プレイリストはなくなり、base_playlist_id は再び必須になりました。ツールで宣言されておらず、廃止された表記でもない名前は unknown_param エラーになります。これは、サーバーが 3.0 までその名前を公開していたことを示す retired_input とは異なるエラーです。

3. 数値上限の名前が正規化されました。 max_results は返される件数を制限し、limit と scan_cap は各ソースから読み取る量を制限します。

4. 不明な引数は拒否されます。 無視される代わりに、型付きの unknown_param エラーが返されるため、名前が変更されたパラメーターは何も起こらず無視されるのではなく、明確にエラーになります。

アップグレード後に spotify_doctor を実行してください。登録されているインターフェース、モジュールを非表示にしたゲート、許可されたスコープを 1 回の呼び出しで報告します。

ドキュメント

• docs/v3-roadmap.md — 3.0 で予定されていることと、そのすべての根底にある 1 つのバグ
• docs/migration-v3.md — 3.0 で廃止されたすべての名前とその置き換え先（代替がない操作も 1 つ含む）
• SPEC.md — すべてのツール、リソース、プロンプト
• ARCHITECTURE.md — 構築方法
• docs/configuration.md — すべての環境変数
• docs/cli.md — tools、call、watch、export、init：MCP クライアントとしての CLI
• docs/schema-budgets.md — モジュールごとのスキーマ予算と登録順序
• docs/statsfm.md — 2 つ目のデータソース stats.fm：セットアップ、ツールの早見表、注意点
• docs/cookbook.md — コピーして使えるエージェントのレシピ
• docs/non-goals.md — v2 で対応しないこと、その理由、代わりに提供するもの
• docs/taste.md — プレイリストを作成する、匿名化された嗜好のショーケース
• docs/wave2-composites.md — 読み取り専用の嗜好コンポジット
• docs/distribution.md — 配布とリリースノート
• docs/faq.md — 認証、Premium、403、ヘッドレス、トークン
• docs/compliance.md — ブランドマーク、帰属表示、送信時の User-Agent
• CONTRIBUTING.md — 開発環境のセットアップと規約
• CHANGELOG.md — リリース履歴

要件

• 再生操作（再生／一時停止／スキップ／シーク／音量／キュー）には Premium が必要です。無料アカウントでも検索、ライブラリ、プレイリストは引き続き利用できます。
• Node 22.9 以降、開発モードの Spotify アプリ（拡張クォータが適用されるまではユーザー 5 人）。
• オーディオブックは Spotify により US/UK/CA/IE/NZ/AU に制限されています。
• 一部のエンドポイントは アプリ登録による制限があります。現在のアプリ登録では、スコープや Premium の有無にかかわらず 403 が返されます。以前からある登録で引き続き 200 が返されるかは未検証です（#1338）。これはツールではなく、アプリ登録の特性です。登録制限のあるエンドポイントを参照してください。

登録制限のあるエンドポイント

一部の Web API エンドポイントはアプリ登録レベルで拒否されます。現在の Spotify アプリ登録では、付与する OAuth スコープやアカウントが Premium かどうかにかかわらず、403 Forbidden が返されます。これは Spotify 側の制限であり、設定ミスではありません。

ここにあるものは、単に「削除」されたわけではありません。 この分類について説明する情報源は 3 つありますが、内容は一致していません。そのため、以下の表には断定的な結論ではなく、実行時の挙動を記載しています。

• Spotify の2026 年 2 月の変更履歴では、一連の操作に [REMOVED] のマークが付けられています。
• 公開中の OpenAPI スキーマでは、同じパスの大半が引き続き公開されています。削除されずに deprecated: true と記載されており、その中には /artists/{id}/top-tracks と、7 つすべての Get Several バッチパスが含まれます。
• 実行時の実態は、どちらのドキュメントにもありません。あなたのアプリ登録に読み取りが許可されているかどうかが実態です。許可のない登録では 403／404／410 が返されます。以前からある登録で引き続き 200 が返されるかは未検証です（#1338）。このリポジトリにはそれを示す調査結果がなく、かつてその根拠として引用された唯一の調査記録では、該当するすべてのパスで 403 が記録されています。

したがって、ここでの 403 はツールではなく登録の特性です。制限対象だからといってツールが非表示になることはなく、ゾンビ化した制限対象ツールもありません。どのツールも、文書化された代替手段を読み取って応答するか、呼び出しを実行して 403 の理由を平易な英語で説明します。正とする一覧は src/gating.ts の GATED_FAMILIES 配列です。GATED_PATH_PATTERNS はこの配列から導出されるため、分類器とこの表に食い違いは生じません。

上記の 8 つのファミリーはいずれも、Spotify の 2026 年 2 月の変更履歴で [REMOVED] とされています。

信頼できる情報源と照らし合わせて、ご自身で一覧を確認してください。

grep -n "id: '" src/gating.ts        # the families, with tools and fallback per row

注記：

• この一覧にあるファミリーは、実行時の分類器であり、ツールが呼び出すことを保証するものではありません。3 つのファミリー（browse-new-releases、me-type-contains、playlist-followers-contains）には、現在有効な呼び出し箇所がありません。これらを使用していたツールは代替手段に移行済みです。将来呼び出しが追加された場合にも 403 の契約が適用され、対象からひそかに漏れることがないよう、パターンは保持されています。
• GET /me/library/contains はゲート対象ではなく、同じプローブで 200 を返しました。このエンドポイントは、check_playlist_following、restore_library_snapshot、レシート検証で使用する保存状態の読み取りを支えています。上記の contains ファミリーは、変更履歴でこのエンドポイントに置き換えられた、ドキュメントに記載されたタイプごとの確認です。（プレイリストの重複クリーンアップツールはこのセットに含まれません。これらは /playlists/{id}/items をページングします。）
• バッチのフォールバック（#725）。 Get Several バッチエンドポイントが 403 を返すと、fetchSeveral はクライアントの既存のキューとバックオフを使い、ID ごとの GET /<kind>/{id} 呼び出しで再試行します。ID ごとのパスはゲート対象のクラスに含まれないため、読み取りは引き続き成功します。レスポンスには degraded: true と、文章内の [degraded: batch endpoint returned 403; … fetched individually] というフッターに加え、structuredContent の degraded_reason が含まれます。これにより、呼び出し元は通常のバッチ読み取りと、項目ごとに往復した読み取りを判別できます。
• Spotify が削除済みとして掲載しているものの、このサーバーではまったくラップしていないエンドポイント（同梱ツールがなく、説明の対象もありません）：/recommendations、/recommendations/available-genre-seeds、/me/apps、/me/chapters、/artists/{id}/related-artists、/audio-features、/audio-analysis、/browse/featured-playlists の読み取り、および /playlists/{id}/tracks ファミリー（/playlists/{id}/items に置き換え済み）。ツールが存在しないことが正確な答えであり、説明すべき 403 もないため、これらは上の表に含まれていません。

このサーバーが対象としないもの

v2 には明文化された非目標の一覧があるため、対象外のリクエストには、対応するかもしれないという曖昧な回答ではなく、明確な回答が得られます。以下の各項目の根拠は SPEC §1に記載されており、 docs/non-goals.mdには、その両方の根拠となる記録があります。各項目で除外されるもの、その根拠となる情報源、そしてサーバーが代わりに提供するものを確認できます。

• オーディオストリーミング、オーディオ分析、オフライン再生
• Web UI、ダッシュボード、MCP UI サーフェス
• マルチテナント運用またはホスト型運用
• あるユーザーの認証情報を複数のユーザー間で共有すること
• 歌詞
• Spotify Connect SDK とネイティブクライアント統合
• 音声コントロール
• Spotify データを使ったモデルのトレーニング、または派生プロフィールのエクスポート
• 2つ目のサードパーティー上流、アドテック、または収益化を目的とする外部へのデータ送信
• Spotify 独自の制御を回避すること

開発

git clone https://github.com/NovaLux12/spotify-mcp-server.git && cd spotify-mcp-server
npm ci && npm run build
cp .env.example .env  # add your Client ID
npm run auth          # one-time login
npm run dev           # run from source
npm test              # unit + MCP smoke tests

Spotify とは提携していません。Spotify Developer Termsに従ってご利用ください。

MIT © Carme99 および NovaLux12 のコントリビューター · calebWei/SpotifyMCP および varunneal/spotify-mcpに謝意を表します。