MCP Claude Spotify

MCP Claude Spotify

Model Context Protocol（MCP）を使用して、Claude Desktop から Spotify を利用できるようにする連携機能です。

0.6.0 で削除 — get-recommendations。 Spotify は、関連アーティスト、オーディオ機能、オーディオ分析、注目のプレイリスト、30 秒のプレビュー URL とともに、2024 年 11 月 27 日に /v1/recommendations を非推奨にしました。この日以降に作成されたアプリは 403 Forbidden を受け取り、開発モードのアプリもアクセスできなくなったため、実質的に誰もこのツールを使用できませんでした。代わりに search-spotify と get-top-tracks を使用してください。Spotify の発表をご覧ください。

機能

• Spotify 認証
• トラック、アルバム、アーティスト、プレイリストを検索
• 再生操作（再生、一時停止、次へ、前へ）
• プレイリストの完全な管理（作成、更新、削除、トラックの並べ替え、カバー画像の管理）
• トップトラックと再生履歴を閲覧
• さまざまな期間におけるユーザーの再生回数上位のトラックにアクセス
• 最近再生したトラックを表示

デモ

要件

• Node.js 20 以降
• Spotify アカウント
• Claude Desktop
• Spotify API 認証情報（Client ID と Client Secret）

インストール

Smithery 経由でのインストール

Smithery 経由で、Claude Desktop 用の MCP Claude Spotify を自動的にインストールするには：

npx -y @smithery/cli@latest mcp add imprvhub/mcp-claude-spotify --client claude

手動インストール

1. このリポジトリをクローンまたはダウンロードします：

git clone https://github.com/imprvhub/mcp-claude-spotify
cd claude-spotify-mcp

2. 依存関係をインストールします：

npm install

3. （ソースコードを変更する場合は）プロジェクトをビルドします：

npm run build

リポジトリには build ディレクトリにビルド済みファイルが含まれているため、ソースコードを変更する予定がなければ、手順 3 は省略できます。

Spotify 認証情報の設定

この MCP を使用するには、Spotify API 認証情報を取得する必要があります：

1. Spotify Developer Dashboard にアクセスします
2. Spotify アカウントでログインします
3. 「Create App」をクリックします
4. アプリ情報を入力します：
   • アプリ名：「MCP Claude Spotify」（または任意の名前）
   • アプリの説明：「Claude Desktop 用の Spotify 連携」
   • ウェブサイト：空欄のままにするか、任意の URL を入力できます
   • リダイレクト URI：重要 - http://127.0.0.1:8888/callback を追加します
5. 利用規約に同意して、「Create」をクリックします
6. アプリのダッシュボードに「Client ID」が表示されます
7. 「Show Client Secret」をクリックして、「Client Secret」を表示します

設定で必要になるため、これらの認証情報を保存してください。

MCP サーバーの実行

MCP サーバーを実行する方法は 2 つあります：

オプション 1：ターミナルから一度だけ認証する（初回セットアップ）

Claude Desktop はサーバーの独自のコピーを起動するため、ターミナルで起動したままのサーバーと Claude が通信するわけではありません。ターミナルでの実行は、一度だけ認証する場合に便利です。SPOTIFY_AUTO_AUTH=true を指定し、保存済みのトークンがない状態でサーバーを起動すると、ブラウザーで Spotify のログイン画面が開きます。

SPOTIFY_CLIENT_ID=your_client_id \
SPOTIFY_CLIENT_SECRET=your_client_secret \
SPOTIFY_AUTO_AUTH=true \
node build/index.js

ブラウザーでリクエストを承認します。ターミナルに「Authorization complete」と表示されたら、Ctrl+C でプロセスを停止します。トークンは ~/.spotify-mcp/tokens.json に保存され、Claude Desktop が起動するコピーによって読み込まれます。

この手順は省略して、代わりに Claude に「Spotify で認証して」と頼むこともできます。同じログインページを開く auth-spotify ツールが実行されます。

オプション 2：Claude Desktop で自動起動する（通常の使用におすすめ）

Claude Desktop は、必要に応じて MCP サーバーを自動的に起動できます。設定するには、次の手順に従います。

設定

Claude Desktop の設定ファイルは、次の場所にあります。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

このファイルを編集して、Spotify MCP の設定を追加します。ファイルが存在しない場合は、新規作成してください。

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["ABSOLUTE_PATH_TO_DIRECTORY/mcp-claude-spotify/build/index.js"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id_here",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

重要：次の値を置き換えてください。

• ABSOLUTE_PATH_TO_DIRECTORY を、MCP をインストールした完全な絶対パスに置き換えます。
  • macOS/Linux の例：/Users/username/mcp-claude-spotify
  • Windows の例：C:\\Users\\username\\mcp-claude-spotify
• your_client_id_here を、Spotify から取得した Client ID に置き換えます。
• your_client_secret_here を、Spotify から取得した Client Secret に置き換えます。

他の MCP がすでに設定されている場合は、「mcpServers」オブジェクト内に「spotify」セクションを追加するだけです。

自動起動スクリプトの設定（任意）

より安定して使用するには、自動起動スクリプトを設定できます。

@echo off
cd %~dp0
node build/index.js

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.spotify.mcp</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/node</string>
        <string>ABSOLUTE_PATH_TO_DIRECTORY/mcp-claude-spotify/build/index.js</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardErrorPath</key>
    <string>/tmp/spotify-mcp.err</string>
    <key>StandardOutPath</key>
    <string>/tmp/spotify-mcp.out</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>SPOTIFY_CLIENT_ID</key>
        <string>your_client_id_here</string>
        <key>SPOTIFY_CLIENT_SECRET</key>
        <string>your_client_secret_here</string>
    </dict>
</dict>
</plist>

[Unit]
Description=Spotify MCP Server for Claude Desktop
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/node ABSOLUTE_PATH_TO_DIRECTORY/mcp-claude-spotify/build/index.js
Restart=on-failure
Environment="SPOTIFY_CLIENT_ID=your_client_id_here"
Environment="SPOTIFY_CLIENT_SECRET=your_client_secret_here"

[Install]
WantedBy=default.target

systemctl --user enable spotify-mcp.service
systemctl --user start spotify-mcp.service

systemctl --user status spotify-mcp.service

開発

npm install
npm run build
npm test

使用方法

1. 設定を変更した後、Claude Desktop を再起動します。
2. Claude で auth-spotify コマンドを使用し、認証プロセスを開始します。
3. アプリケーションを承認するためのブラウザーウィンドウが開きます。
4. Spotify アカウントでログインし、アプリケーションを承認します。
5. 重要：認証が成功したら、MCP のツールレジストリと WebSocket セッショントークンキャッシュを正しく初期化するため、Claude Desktop を再起動します。
6. 再起動後、すべての Spotify MCP ツールが正しく登録され、使用できるようになります。

MCP サーバーは、Claude Desktop が管理する子プロセスとして実行されます。Claude の実行中は、claude_desktop_config.json の設定に基づいて Node.js サーバープロセスが自動的に起動・管理されます。

セキュリティに関する注意事項

• 認証は CSRF から保護されています。 ログイン URL にはランダムな state 値が含まれ、コールバックではコードを交換する前にその値を検証します。0.6.0 より前のバージョンでは state が送信されなかったため、ブラウザーで開いた任意のページからループバックコールバックにアクセスし、別の Spotify アカウントを紐付けることができました。
• トークンファイルは所有者のみが読み取れます。 ~/.spotify-mcp/tokens.json には有効期間の長いリフレッシュトークンが保存されます。現在は 700 のディレクトリ内に、モード 600 で書き込まれます。以前はデフォルトのモードで作成されていたため、マシン上のすべてのアカウントから読み取ることができました。
• ポートを空けるためにプロセスを終了することはありません。 ポート 8888 が使用中の場合、サーバーはその旨を報告して停止します。以前のバージョンでは lsof -i:8888 -t | xargs kill -9（Windows では同等の taskkill）を実行しており、開発で非常によく使われるこのポートを使用していた無関係なプロセスを SIGKILL で強制終了していました。
• ツールの引数に含まれる ID は検証されます。 トラック、プレイリスト、デバイスの ID は API パスやクエリ文字列に使用されるため、通常の Spotify ID のみが受け付けられ、それ以外はリクエストの構築前に拒否されます。
• コールバックはループバックのみ（127.0.0.1）で待ち受けます。 以前の express リスナーはすべてのネットワークインターフェースにバインドされていたため、同じネットワーク上の誰でも /login や /callback にアクセスできました。コンテナーでは AUTH_BIND_HOST=0.0.0.0 を指定することで、待ち受け範囲を広げられます。
• 認証が完了すると、コールバックサーバーはシャットダウンします。 セッションが終わるまでバインドされたままになることはありません。

利用可能なツール

認証

auth-spotify

Spotify の認証プロセスを開始します。

検索

search-spotify

トラック、アルバム、アーティスト、プレイリストを検索します。

パラメーター：

• query：検索テキスト
• type：検索対象の種類（track、album、artist、playlist）
• limit：結果の件数（1～10、デフォルト：5）

再生の操作

get-current-playback

現在の再生状態に関する情報を取得します。

play-track

アクティブなデバイスで指定したトラックを再生します。

パラメーター：

• trackId：Spotify のトラック ID
• deviceId：（任意）再生に使用する Spotify デバイス ID

pause-playback

現在の再生を一時停止します。

next-track

次のトラックにスキップします。

previous-track

前のトラックに戻ります。

プレイリストの管理

get-user-playlists

ユーザーのプレイリスト一覧を取得します。

パラメーター：

• limit：（任意）取得するプレイリストの件数（1～50、デフォルト：20）
• offset：（任意）取得を開始するプレイリストのインデックス（デフォルト：0）

create-playlist

現在のユーザーの新しいプレイリストを作成します。

パラメーター：

• name：プレイリスト名
• description：（任意）説明
• public：（任意）公開するか非公開にするか

update-playlist

プレイリストの名前、説明、公開／非公開の設定、または共同編集の設定を更新します。

パラメーター：

• playlistId：プレイリストの Spotify ID
• name：（任意）プレイリストの新しい名前
• description：（任意）新しい説明
• public：（任意）プレイリストを公開するかどうか
• collaborative：（任意）プレイリストを共同編集可能にするかどうか（先に public を false に設定する必要があります）

delete-playlist

プレイリストのフォローを解除し（ライブラリから削除し）ます。プレイリストは Spotify 上に残りますが、ライブラリには表示されなくなります。

パラメーター：

• playlistId：プレイリストの Spotify ID

get-playlist-tracks

ページネーションに対応した形で、プレイリスト内のトラックを取得します。

パラメーター：

• playlistId：プレイリストの Spotify ID
• limit：（任意）取得するトラックの件数（1～50、デフォルト：20）
• offset：（任意）取得を開始するトラックのインデックス（デフォルト：0）

add-tracks-to-playlist

プレイリストにトラックを追加します。

パラメーター：

• playlistId：プレイリスト ID
• trackIds：トラック ID の配列

remove-tracks-from-playlist

プレイリストからトラックを削除します。

パラメーター：

• playlistId：プレイリストの Spotify ID
• trackIds：削除する Spotify トラック ID の配列

reorder-playlist-tracks

プレイリスト内のトラックを並べ替え、指定した範囲のトラックを新しい位置に移動します。

パラメーター：

• playlistId：プレイリストの Spotify ID
• rangeStart：移動する最初のトラックの位置
• insertBefore：トラックを挿入する位置
• rangeLength：（任意）移動するトラック数（デフォルト：1）

get-playlist-cover

プレイリストのカバー画像を取得します。

パラメーター：

• playlistId：プレイリストの Spotify ID

upload-playlist-cover

プレイリストのカスタムカバー画像をアップロードします（Base64 エンコードされた JPEG、最大 256KB）。

パラメーター：

• playlistId：プレイリストの Spotify ID
• imageBase64：Base64 エンコードされた JPEG 画像

ディスカバリーと履歴

get-top-tracks

指定した期間に再生された回数が最も多いユーザーのトラックを取得します。

パラメーター：

• limit：（任意）取得するトラック数（1～50、デフォルト：20）
• offset：（任意）取得する最初のトラックのインデックス（デフォルト：0）
• time_range：（任意）親和性を計算する期間：
  • short_term：直近約4週間
  • medium_term：直近約6か月（デフォルト）
  • long_term：数年分のデータ

get-recently-played

ユーザーが最近再生したトラックを取得します。

パラメーター：

• limit：（任意）取得するトラックの最大数（1～50、デフォルト：20）
• before：（任意）ミリ秒単位の Unix タイムスタンプ。この時刻より前に再生されたトラックを返します
• after：（任意）ミリ秒単位の Unix タイムスタンプ。この時刻より後に再生されたトラックを返します

トラブルシューティング

「Server disconnected」エラー

Claude Desktop で「MCP Spotify: Server disconnected」というエラーが表示される場合：

1. サーバーが実行中か確認します：

   • ターミナルを開き、プロジェクトディレクトリから node build/index.js を手動で実行します
   • サーバーが正常に起動した場合は、ターミナルを開いたまま Claude を使用します

2. 設定を確認します：

   • claude_desktop_config.json の絶対パスがシステムに合っていることを確認します
   • Windows のパスには二重のバックスラッシュ（\\）を使用していることを再確認します
   • ファイルシステムのルートからの完全なパスを使用していることを確認します

3. 自動起動オプションを試します：

   • 「自動起動スクリプトの設定」セクションの説明に従って、オペレーティングシステムに応じた自動起動スクリプトを設定します
   • これにより、必要なときにサーバーが常に実行されるようになります

ブラウザーが自動的に開かない

認証中にブラウザーが自動的に開かない場合は、次の URL に手動でアクセスします： http://127.0.0.1:8888/login

認証エラー

Spotify Developer ダッシュボードでリダイレクト URI が正しく設定されていることを確認します： http://127.0.0.1:8888/callback

サーバー起動エラー

次の点を確認します：

• 環境変数が claude_desktop_config.json または起動スクリプトで正しく設定されている
• Node.js がインストールされており、互換性がある（v16+）
• 必要なポート（8888）が使用可能で、ファイアウォールによってブロックされていない
• 指定された場所でスクリプトを実行する権限がある

Claude にツールが表示されない

認証後に Claude に Spotify ツールが表示されない場合：

• 認証が完了した後、Claude Desktop を再起動したことを確認します
• Claude Desktop のログで MCP の通信エラーを確認します
• MCP サーバーのプロセスが実行中であることを確認します（手動で実行して確認してください）
• MCP サーバーが Claude Desktop の MCP レジストリに正しく登録されていることを確認します

サーバーが実行中か確認する

サーバーが実行中か確認するには：

• Windows：「タスク マネージャー」を開き、「詳細」タブに移動して「node.exe」を探します
• macOS/Linux：ターミナルを開き、ps aux | grep node を実行します

サーバーが実行中でない場合は、手動で起動するか、自動起動方式を使用してください。

テスト

このプロジェクトには、コードの品質と機能を保証するための自動テストが含まれています。テストスイートでは、TypeScript に対応した Jest を使用し、以下をカバーしています。

• Zod スキーマの検証 - すべての入力スキーマがデータを正しく検証することを確認します
• Spotify API との連携 - API リクエストの処理とエラー処理をテストします
• MCP サーバーの機能 - ツールが適切に登録され、実行されることを確認します

テストの実行

まず、すべての開発用依存関係がインストールされていることを確認してください。

npm install

すべてのテストを実行するには：

npm test

特定のテストファイルを実行するには：

npm test -- --testMatch="**/tests/schemas.test.ts"

ESM モジュールで問題が発生した場合は、Node.js v16 以降を使用していること、および NODE_OPTIONS 環境変数に package.json で設定されている --experimental-vm-modules フラグが含まれていることを確認してください。

テストの構成

• tests/schemas.test.ts：入力検証スキーマのテスト
• tests/spotify-api.test.ts：Spotify API との連携テスト
• tests/server.test.ts：MCP サーバーの機能テスト

テストの追加

新しい機能を追加する際は、対応するテストも追加してください。

1. 新しいスキーマについては、schemas.test.ts に検証テストを追加します
2. Spotify API 関数については、spotify-api.test.ts にテストを追加します
3. MCP ツールについては、server.test.ts にテストを追加します

すべてのテストは、Jest と TypeScript を使用した ESM モジュール形式で記述してください。

セキュリティに関する注意事項

• Client ID と Client Secret は絶対に共有しないでください
• セッション間および複数のインスタンス間で永続化できるよう、アクセストークンはユーザーのホームディレクトリにある ~/.spotify-mcp/tokens.json に保存されるようになりました
• ユーザーデータはディスクに保存されません

アプリケーションへのアクセス権の取り消し

セキュリティ上の理由から、次の場合は Spotify アカウントへのアプリケーションのアクセス権を取り消すことをお勧めします。

• この連携を使用しなくなった場合
• 不正アクセスが疑われる場合
• 認証の問題をトラブルシューティングする場合

アクセス権を取り消すには：

1. Spotify アカウントページにアクセスします
2. メニューから「Apps」を選択します
3. 「MCP Claude Spotify」（またはアプリに付けた名前）を見つけます
4. 「REMOVE ACCESS」をクリックします

これにより、すべてのアクセストークンとリフレッシュトークンが直ちに無効になります。次回 auth-spotify コマンドを使用する際は、アプリケーションを再度認証する必要があります。

コントリビューション

コントリビューションを歓迎します。以下のガイドラインに従ってください。

開発ワークフロー

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更を加えます
4. テストを実行して、すべて成功することを確認します（npm test）
5. 変更をコミットします（git commit -m 'Add some amazing feature'）
6. ブランチにプッシュします（git push origin feature/amazing-feature）
7. プルリクエストを作成します

コードスタイルガイドライン

このプロジェクトでは、以下のコーディング規約に従います。

• 厳密な型チェックを有効にして TypeScript を使用します
• ESM モジュール形式に従います
• インデントには 2 つのスペースを使用します
• 変数と関数には camelCase を使用します
• クラスとインターフェースには PascalCase を使用します
• JSDoc コメントで関数をドキュメント化します
• 行の長さは 100 文字未満にします

プロジェクト構成

プロジェクトは以下の構成になっています。

mcp-claude-spotify/
├── src/               # Source code
├── build/             # Compiled JavaScript
├── tests/             # Test files
├── public/            # Public assets
└── ...

プルリクエストのプロセス

1. コードがスタイルガイドラインに従っていることを確認します
2. 必要に応じてドキュメントを更新します
3. 新機能のテストを追加します
4. すべてのテストが成功することを確認します
5. メンテナーが PR をレビューします

関連リンク

• Model Context Protocol
• Spotify Web API ドキュメント
• Claude Desktop
• MCP Series

ライセンス

このプロジェクトは Mozilla Public License 2.0 の下でライセンスされています。詳細については、LICENSE ファイルをご覧ください。