SpotifyMCP

Spotify Web APIをラップするMCPサーバーで、AIアシスタント(Claudeなど)が再生の制御、ポッドキャストやオーディオブックを含む全カタログの検索、ライブラリとプレイリストの管理、リスニング傾向の把握を可能にします。

なぜこれなのか

ほとんどのSpotify MCPサーバーは薄いラッパーです。これはデフォルトになるように作られています:

• 完全なAPIカバレッジ — 標準の開発者トークンで呼び出せる非推奨でないSpotify Web APIエンドポイントはすべてツールでカバーされています(再生、検索、カタログ、オーディオブック、パーソナライゼーション、ライブラリ、プレイリスト、フォロー)。

• 非推奨化に正直 — Spotifyは新規アプリからレコメンデーション、関連アーティスト、オーディオフィーチャー/分析、ジャンルシード、注目のプレイリストを削除しました。それらを公開し続けるサーバーは実行時に失敗するツールを出荷しますが、これはそうではありません。

• テスト済み — クライアント(トークン更新、レート制限、ページネーション)とすべてのツールハンドラーに対する完全なユニットテストスイートに加え、エンドツーエンドのMCPプロトコルスモークテストを備えています。多くの代替品はテストがゼロです。

• すべてページネーション対応 — ライブラリとプレイリスト一覧のfetch_allは、50件の1ページで黙って切り捨てるのではなく、すべてのページを走査します(最大500件)。

• ポッドキャストは第一級市民 — エピソードはどこでも機能します: 再生中、キュー、検索して再生。いくつかの競合製品はポッドキャストをまったく認識できません。

• デバイス対応の再生 — デバイスの一覧表示、再生の転送、マルチルーム構成向けに特定のデバイスへのコマンド指定が可能です。

• 堅牢な認証 — サイレント更新付きPKCEフロー、永続的なmode-600トークンキャッシュ、サーバーとコンテナ向けのヘッドレス貼り付けフロー(SPOTIFY_HEADLESS=1)。

Related MCP server: Spotify MCP Server

機能

再生(15ツール) — 再生中/現在再生中のポーリング、再生(URI指定、または名前から直接再生するplay_from_search)、一時停止、スキップ、前へ、シーク、音量、シャッフル、リピート、キューの表示/追加、デバイス一覧、再生の転送。

検索とカタログ — トラック/アーティスト/アルバム/プレイリスト/ショー/エピソードにわたる統合検索。トラック、アーティスト、アーティストのアルバム、アルバム、アルバムのトラック、ショー、ショーのエピソード、エピソード、プロフィール(get_me)の詳細ルックアップ。

オーディオブック — タイトル、チャプター、チャプター検索、保存済みオーディオブック(Spotifyにより米国/英国/カナダ/アイルランド/ニュージーランド/オーストラリアに市場制限)。

パーソナライゼーション — 3つの期間にわたるトップトラックとアーティスト、最近再生した曲。

ライブラリ — 保存済みトラック/アルバム/ショー/エピソード(オプションで完全なページネーション)。/me/library URIによる統合的な保存/削除/確認。

プレイリスト — 完全なCRUDに加え、アイテム管理(追加/削除/並べ替え)、カバーアートの取得とカスタムカバーのアップロード(アップロードにはugc-image-uploadスコープが必要)。

フォロー — フォロー中のアーティスト一覧とフォロー状態の確認。

さらに公開: 7つのMCPリソース(プロフィール、プレイヤー状態、キュー、トップトラック/アーティスト、最近再生した曲、プレイリスト)と4つのプロンプトテンプレート(DJセット、ムードプレイリスト、好みの要約、ディスカバリーの代替)。

要件と制限

• 再生制御にはSpotify Premiumが必要です(再生、一時停止、スキップ、シーク、音量、シャッフル、リピート、キュー、転送)。無料アカウントは認証して検索/カタログ/ライブラリ/プレイリストのツールを使用できますが、すべての再生コマンドはSpotifyからのPremium必須エラーで失敗します。

• fetch_allのページネーションは1回の呼び出しで最大500件まで走査します(暴走ループ防止)。それを超える場合はlimit/offsetページングを使用してください。

• オーディオブックツールはSpotifyにより米国、英国、カナダ、アイルランド、ニュージーランド、オーストラリアに市場制限されています。

• Spotifyの開発者モードでは、拡張クォータが付与されるまでアプリごとに最大5人の認可ユーザーが許可されます。

クイックセットアップ

1. Spotifyアプリを作成する

各ユーザーはClient IDを取得するために独自のSpotifyアプリが必要です — これがSpotifyがどのアプリがAPIリクエストを行っているかを識別する方法です。

1. Spotify Developer Dashboardにアクセスし、新しいアプリを作成します。

2. アプリ設定で、次のRedirect URIを正確に追加します(一致しない場合、Spotifyはログインを拒否します):

http://127.0.0.1:8888/callback

3. 保存します。Client IDをコピーします。

2. 認証

以下のコマンドを一度実行してSpotifyアカウントにログインします。your_client_id_hereをステップ1のClient IDに置き換えます。ブラウザウィンドウが開き、承認すると~/.spotify-mcp/tokens.jsonにトークンが保存されます。サーバーが自動的に更新するため、再度行う必要はありません。

macOS / Linux:

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

ヘッドレス/リモートホスト(MCPサーバーを実行するマシンにブラウザがない場合):

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

認証URLが表示されます。任意のブラウザ(例: ノートPC)でフローを完了し、リダイレクトURLをプロンプトに貼り付けます。ホームラボ、CI、エージェントランタイムに便利です。

ヘッドレス認証(ブラウザのないホスト)

ブラウザのないホスト(例: クラウドVM、Dockerコンテナ、リモートサーバー)でこのMCPサーバーを実行している場合は、SPOTIFY_HEADLESS=1環境変数を設定します。認証フローはローカルHTTPコールバックサーバーをスキップし、代わりにブラウザでアプリを承認した後にリダイレクトURLを貼り付けるよう求めます。

手順

1. 環境にSPOTIFY_HEADLESS=1を設定します

2. サーバーを実行します — アプリを承認するURLが表示されます

3. 別のマシンのブラウザでURLを開きます

4. 承認後、ブラウザはリダイレクトURIにリダイレクトします

5. アドレスバーから完全なURLをコピーします

6. サーバーのプロンプトに貼り付けます

理由

デフォルトの認証フローはopenパッケージでブラウザを開き、127.0.0.1:8888でローカルHTTPコールバックサーバーを実行します。これは、MCPサーバーがopen()するブラウザのないヘッドレスホスト(ホームラボ、CI、エージェントランタイム)で実行され、127.0.0.1:8888コールバックにユーザーのマシンから到達できない場合に壊れます。

SPOTIFY_HEADLESS=1はURL貼り付けフローに切り替えます: 認証URLがstdoutに表示され、オペレーターが任意のブラウザ(ノートPC、スマートフォン)でフローを完了し、完全なリダイレクトURLを貼り付けます。コードと状態はサーバー側で抽出・交換されます。マシン間で動作します。

Windows(コマンドプロンプト):

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

Windows(PowerShell):

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

3. Claude Desktopを設定する

claude_desktop_config.jsonを開きます:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: Claude Desktopを開く → 設定 → 開発者 → 設定を編集

mcpServersブロックを追加します(your_client_id_hereをClient IDに置き換えます):

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

Claude Desktopを完全に終了して再起動します。チャット入力のハンマーアイコンでサーバーが接続されたことを確認できます。

代替: Claude Code

Claude Codeを使用している場合、JSONを手動で編集せずにサーバーを追加します:

claude mcp add spotify -- npx -y @novalux12/spotify-mcp@latest
# then set SPOTIFY_CLIENT_ID in your shell or MCP env:
export SPOTIFY_CLIENT_ID=your_client_id_here

またはプロジェクトルートの.mcp.jsonに追加します — 上記と同じcommand/args/envの形式です。

AIエージェント向けコマンド

任意のコーディングエージェント(Claude Code、OpenClaw、Cursor、Aiderなど)が、1回の貼り付けでサーバーのインストール、ビルド、認証、登録を実行できます。Client IDを渡して実行させます:

git clone https://github.com/NovaLux12/spotify-mcp-server.git && cd spotify-mcp-server \
  && npm ci && npm run build \
  && SPOTIFY_CLIENT_ID=your_client_id_here npm run auth

次に、ホストのMCP設定を<repo>/dist/index.jsに向け、envにSPOTIFY_CLIENT_IDを設定します(形式は以下)。エージェントは最後にget_meツールを一度呼び出すべきです — 1回のラウンドトリップで認証、スコープ、トランスポートを証明できます。

OpenClaw

~/.openclaw/openclaw.jsonのmcp.serversに追加します:

"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" }
}

次にOpenClawゲートウェイを再起動してサーバーを再生成します。ヘッドレスボックスですか? ブラウザのある任意のマシンでSPOTIFY_HEADLESS=1を指定して認証ステップを実行します(上記参照) — どちらの場合もトークンは~/.spotify-mcp/tokens.jsonに保存されます。

問題が発生した場合: doctorスキルをインストールする

このリポジトリにはskills/spotify-mcp-doctor/SKILL.mdが同梱されています — このREADMEを読み直す代わりにエージェントが実行できる手続き型の診断です。実際の障害モードを順に確認します: 配線 → バイナリ → アプリ資格情報 → トークンの鮮度 → エラー分類(Premium vs 開発モードの許可リスト vs 市場制限 vs 非推奨化)。インストール:

cp -r skills/spotify-mcp-doctor ~/.openclaw/workspace/skills/   # OpenClaw
# or drop it into .claude/skills/ for Claude Code projects

あとはエージェントにこう頼むだけです: 「Spotifyツールが失敗しています — spotify doctorスキルを実行してください。」

使用方法

接続後、Claudeに次のようなことを尋ねられます:

• 「私のトップSpotifyトラックは何ですか?」

• 「勉強用のチルなローファイ曲のプレイリストを作って」

• 「Blinding Lightsという曲をワークアウトプレイリストに追加して」

• 「最近一番よく聴いているアーティストは誰ですか?」

• 「深夜ドライブの雰囲気のプレイリストを作って」

トラブルシューティング

• 最初のツール呼び出しで「Not authenticated」 — npx -y @novalux12/spotify-mcp@latest auth(またはクローンからnpm run auth)を実行し、ブラウザフローを完了します。トークンは~/.spotify-mcp/tokens.jsonに保存され、自動的に更新されます。

• Redirect URIの不一致 — SpotifyアプリのリダイレクトURIは正確にhttp://127.0.0.1:8888/callback(末尾スラッシュなし)である必要があります。アプリ設定を保存して再試行してください。

• ポート8888が使用中 — 別のプロセスがコールバックポートを保持しています。停止するか、SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888/callbackで別のポートと一致するDashboard設定を使用して空きポートを選択してください。

• ヘッドレス/Docker — authの前にSPOTIFY_HEADLESS=1を設定します。プロンプトが表示されたらリダイレクトURLを貼り付けます(上記参照)。

免責事項

これは個人プロジェクトであり、Spotifyとは提携しておらず、Spotifyによる推奨も受けていません。いかなる種類の保証もなく現状のまま提供されます。Spotify Developer Terms of Serviceに従って責任を持って使用してください。作者は本ソフトウェアの使用から生じる誤用や結果について責任を負いません。

開発

git clone https://github.com/NovaLux12/spotify-mcp-server.git
cd spotify-mcp-server
npm install
npm run build

.env.exampleを.envにコピーしてClient IDを入力し、次に:

npm run auth   # authenticate with Spotify
npm run dev    # run from source (no build needed)

Node 22.9+が必要です(--env-file-if-existsサポート)。.envファイルは不要です — 環境変数はホスト設定またはコマンドラインから取得されます。

テスト

npm test   # node:test runner — unit tests for the client and every tool module, plus an MCP protocol smoke test

謝辞

• calebWei/SpotifyMCP — このプロジェクトが成長した元の認証フローと再生の土台。

• varunneal/spotify-mcp — ツールのカバレッジと使いやすさの品質基準として使用されたリファレンス実装。

ライセンス

MIT © Carme99 および NovaLux12コントリビューター。