spotify-mcp

spotify-mcp

AI に話しかけて Spotify を操作できます。Claude Desktop、Claude Code、 Cursor、その他の MCP クライアントで使える MCP サーバーです。

You: 初期の Bill Evans のような曲をかけて AI: ▶ 再生中： 「Peace Piece」— Bill Evans · Everybody Digs Bill Evans

You: いいね、アルバム全体をキューに追加して、この曲を保存して AI: ➕ Everybody Digs Bill Evans をキューに追加しました · ❤️ 「Peace Piece」をライブラリに保存しました

現行（2026年2月以降）の Spotify Web API に対応しています。以前の Spotify MCP サーバーの多くはこれらの変更より前に作られているため、一部が正常に動作しません。

要件

• Spotify Premium — Spotify の再生操作に必要です（また、2026年2月以降は開発者アプリの作成にも必要です）。
• Node.js ≥ 20

クイックスタート

npx -y @xavifabregat/spotify-mcp init

ウィザードでは、独自の（無料の）Spotify 開発者アプリの作成手順を案内し、Client ID を尋ねた後、アカウントを接続するためのブラウザーを開きます。所要時間は約2分です。

独自のアプリが必要な理由は、Spotify がサードパーティ製アプリのユーザー数を少数に制限しているためです。そのため、各ユーザーが自分のアプリを用意します。ウィザードを使えば、簡単に設定できます。クライアントシークレットは不要です（PKCE）。トークンはお使いのマシンの ~/.spotify-mcp/ に保存され、サイレントに更新されます。

正確に設定する必要がある項目は、アプリの Redirect URI です。

http://127.0.0.1:8888/callback

MCP クライアントに追加する

Claude Code

claude mcp add -s user spotify -- npx -y @xavifabregat/spotify-mcp

Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json） または Cursor（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "spotify": {
      "command": "npx",
      "args": ["-y", "@xavifabregat/spotify-mcp"]
    }
  }
}

クライアントを再起動して、話しかけてみましょう。

ツール

ツール	機能
play	自然文のクエリ（検索 → 最適な結果を選択 → 再生）または Spotify URI で再生します
playback	一時停止／再開／次へ／前へ／シーク／音量／シャッフル／リピート
now_playing	現在のトラック、再生位置、デバイス、モードを表示します
queue	トラックをキューに追加します。次に再生されます
devices	デバイスを一覧表示し、再生先を切り替えます
search	トラック／アルバム／アーティスト／プレイリストを検索します（種類ごとに最大10件 — API の上限）
get_playlists	プレイリストを一覧表示します
get_playlist_items	プレイリストのトラックを表示します（自分のプレイリストまたは共同編集プレイリストのみ — API の制限）
modify_playlist	プレイリストを作成し、トラックを追加します
library	ライブラリ内のアイテムを保存／削除／確認します
authenticate	会話内から Spotify にログインします

設計

• ツールはエンドポイントではなく、意図を表します。 「Radiohead をかけて」と言うと、1回のツール呼び出しでサーバーが検索し、最適な結果を選び、再生を開始して、選んだ曲を報告します。必要なら修正できます。検索 → 選択 → 再生という一連の呼び出しは不要です。
• シンプルな構成です。 API エンドポイントごとにツールを用意するのではなく、11個のツールに絞ることで、さまざまな AI クライアントで正確にツールを選択でき、コンテキストも軽く保てます。
• レスポンスは Spotify URI を含む簡潔なテキスト形式です。 そのため、「それをキューに追加して」といった追加の指示も、再検索せずに続けられます。生の API ペイロードがモデルに渡されることはありません。
• エラーは解決方法を示します。 アクティブなデバイスがない場合、レスポンスにデバイス一覧と選択方法が表示されます。ログインしていない場合は、authenticate ツールを案内します。モデルはスタックトレースではなく、解決方法を伝えます。

トラブルシューティング

• 「アクティブな Spotify デバイスがありません」 — Spotify の API で操作できるのは、起動中のアプリのみです。どこかで Spotify を開いてください。起動したばかりの場合は、再生／一時停止を一度タップしてください。オンラインのデバイスが1台だけの場合、ツールは自動的にそのデバイスを対象にします。
• ログイン中に INVALID_CLIENT: Invalid redirect URI が発生する — アプリの設定にあるリダイレクト URI が http://127.0.0.1:8888/callback と完全に一致していません（Spotify では localhost は拒否されます）。
• ログイン中にポート 8888 が使用中になる — SPOTIFY_REDIRECT_PORT に空いているポートを設定し、それに対応するリダイレクト URI を登録してください。
• 「トークンの更新に失敗しました」 — 再度ログインするには、npx -y @xavifabregat/spotify-mcp auth を実行してください（例：クライアント ID を変更した後）。
• 設定の優先順位 — SPOTIFY_CLIENT_ID 環境変数は、init によって書き込まれる ~/.spotify-mcp/config.json より優先されます。

開発

git clone https://github.com/XavierFabregat/spotify-mcp.git
cd spotify-mcp
npm install
npm run build
npm run inspect   # MCP Inspector against the local build

構成：src/auth.ts（OAuth PKCE ＋ トークンストア）・src/spotify.ts（型付き API クライアント）・src/tools/（ツールの実装）・src/format.ts（簡潔な出力）。

ライセンス

MIT © Xavi Fabregat