MCP クロード Spotify

特徴

• Spotify認証

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

• 再生コントロール（再生、一時停止、次、前）

• プレイリストの作成と管理

• パーソナライズされたおすすめ情報を入手

• さまざまな期間にわたってユーザーが最もよく再生したトラックにアクセスします

デモ

要件

• Node.js 16以上

• Spotifyアカウント

• クロードデスクトップ

• Spotify API 資格情報 (クライアント ID とクライアント シークレット)

インストール

Smithery経由でインストール

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

手動でインストールする

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

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

3. プロジェクトをビルドします (ソース コードを変更する場合)。

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

Spotify認証情報の設定

この MCP を使用するには、Spotify API 資格情報を取得する必要があります。

1. Spotify開発者ダッシュボードへ

2. Spotifyアカウントでログイン

3. 「アプリを作成」をクリックします

4. アプリ情報を入力してください:

   • アプリ名:「MCP Claude Spotify」（またはお好きな名前）

   • アプリの説明: 「Claude Desktop 向け Spotify 統合」

   • ウェブサイト: 空白のままにするか、任意のURLを入力してください

   • リダイレクトURI:重要- http://127.0.0.1:8888/callbackを追加

5. 利用規約に同意して「作成」をクリックします

6. アプリのダッシュボードに「クライアントID」が表示されます。

7. 「クライアントシークレットを表示」をクリックすると「クライアントシークレット」が表示されます。

これらの資格情報は構成に必要となるため保存してください。

MCPサーバーの実行

MCP サーバーを実行するには 2 つの方法があります。

オプション 1: 手動で実行する (初回セットアップとトラブルシューティングに推奨)

1. ターミナルまたはコマンドプロンプトを開きます

2. プロジェクトディレクトリに移動する

3. サーバーを直接実行します。

Claude Desktopの使用中は、このターミナルウィンドウを開いたままにしてください。ターミナルを閉じるまでサーバーは稼働し続けます。

オプション 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の設定を追加します。ファイルが存在しない場合は作成してください。

重要: 置き換え:

• ABSOLUTE_PATH_TO_DIRECTORYは、MCP をインストールした完全な絶対パスです。

  • macOS/Linuxの例: /Users/username/mcp-claude-spotify

  • Windows の例: C:\\Users\\username\\mcp-claude-spotify

• your_client_id_here Spotify から取得したクライアント ID です

• your_client_secret_hereに Spotify から取得したクライアントシークレットを入力します。

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

自動起動スクリプトの設定（オプション）

より信頼性の高いエクスペリエンスを実現するために、自動起動スクリプトを設定できます。

1. プロジェクト ディレクトリに、次の内容を含むstart-spotify-mcp.batという名前のファイルを作成します。

2. このBATファイルへのショートカットを作成します

3. Win+Rを押して、 shell:startupと入力してEnterを押します。

4. このフォルダにショートカットを移動すると、Windows で起動するようになります。

5. ~/Library/LaunchAgents/に次の内容を含むcom.spotify.mcp.plistという名前のファイルを作成します。

2. パスと資格情報を実際の値に置き換えます

3. エージェントをロードするには、 launchctl load ~/Library/LaunchAgents/com.spotify.mcp.plist

4. ~/.config/systemd/user/にspotify-mcp.serviceという名前のファイルを作成します (ディレクトリが存在しない場合は作成します)。

2. パスと資格情報を実際の値に置き換えます

3. サービスを有効にして開始します。

4. ステータスを確認するには:

使用法

1. 設定を変更した後、Claude Desktopを再起動します。

2. Claudeでは、 auth-spotifyコマンドを使用して認証プロセスを開始します。

3. アプリケーションを承認するためのブラウザウィンドウが開きます

4. Spotifyアカウントでログインし、アプリケーションを承認します

5. 重要: 認証が成功したら、Claude Desktopを再起動して、MCPのツールレジストリとWebSocketセッショントークンキャッシュを適切に初期化します。

6. 再起動後、すべてのSpotify MCPツールが適切に登録され、使用できるようになります。

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

利用可能なツール

認証-Spotify

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

Spotifyで検索

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

パラメータ:

• query : 検索テキスト

• type : 検索の種類（トラック、アルバム、アーティスト、プレイリスト）

• limit : 結果件数 (1-50)

再生トラック

特定のトラックを再生します。

パラメータ:

• trackId : SpotifyトラックID

• deviceId : (オプション) 再生するSpotifyデバイスID

現在の再生を取得

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

一時停止-再生

再生を一時停止します。

次のトラック

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

前のトラック

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

ユーザーのプレイリストを取得する

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

プレイリストを作成

新しいプレイリストを作成します。

パラメータ:

• name : プレイリスト名

• description : (オプション) 説明

• public : (オプション) 公開か非公開か

プレイリストにトラックを追加

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

パラメータ:

• playlistId : プレイリストID

• trackIds : トラックIDの配列

推奨事項を取得する

シードに基づいて推奨事項を取得します。

パラメータ:

• seedTracks : (オプション) トラックIDの配列

• seedArtists : (オプション) アーティストIDの配列

• seedGenres : (オプション) ジャンルの配列

• limit : (オプション) 推奨の数 (1-100)

トップトラックを取得する

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

パラメータ:

• limit : (オプション) 返されるトラックの数 (1-50、デフォルト: 20)

• offset : (オプション) 返される最初のトラックのインデックス (デフォルト: 0)

• time_range : (オプション) 親和性を計算する期間:

  • short_term : 過去約4週間

  • medium_term : 過去約6か月（デフォルト）

  • long_term : 数年間のデータ

トラブルシューティング

「サーバーが切断されました」エラー

Claude Desktop で「MCP Spotify: サーバーが切断されました」というエラーが表示される場合:

1. サーバーが実行中であることを確認します:

   • ターミナルを開き、プロジェクトディレクトリからnode build/index.js手動で実行します。

   • サーバーが正常に起動したら、このターミナルを開いたままClaudeを使用します。

2. 設定を確認してください:

   • claude_desktop_config.jsonの絶対パスがシステムに合っていることを確認してください

   • Windowsのパスに二重のバックスラッシュ（ \\ ）を使用していることを確認してください

   • ファイルシステムのルートからの完全なパスを使用していることを確認してください

3. 自動起動オプションを試してください:

   • 「自動起動スクリプトの設定」セクションの説明に従って、オペレーティング システムの自動起動スクリプトを設定します。

   • これにより、必要なときにサーバーが常に実行されるようになります。

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

認証中にブラウザが自動的に開かない場合は、手動でアクセスしてください: http://127.0.0.1:8888/login

認証エラー

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

サーバー起動エラー

次の点を確認してください。

• 環境変数がclaude_desktop_config.jsonまたは起動スクリプトで正しく設定されていること

• Node.jsがインストールされ、互換性がある（v16以上）

• 必要なポート（8888）が利用可能であり、ファイアウォールによってブロックされていない

• 指定された場所でスクリプトを実行する権限があります

クロードにツールが表示されない

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

• 認証が成功したら、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 サーバー機能 - ツールの適切な登録と実行を保証します

テストの実行

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

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

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

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 モジュール形式を使用して記述する必要があります。

セキュリティノート

• クライアントIDとクライアントシークレットを決して共有しないでください

• アクセス トークンは、セッションと複数のインスタンス間の永続性を可能にするために、ユーザーのホーム ディレクトリの~/.spotify-mcp/tokens.jsonに保存されるようになりました。

• ユーザーデータはディスクに保存されません

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

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

• この統合はもう使用していません

• 不正アクセスが疑われる

• 認証の問題をトラブルシューティングしています

アクセスを取り消すには:

1. Spotifyアカウントページに移動します

2. メニューの「アプリ」に移動します

3. 「MCP Claude Spotify」（またはアプリに付けた名前）を見つけます

4. 「アクセスを削除」をクリックします

これにより、すべてのアクセストークンとリフレッシュトークンが直ちに無効になります。次回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つのスペースを使用します

• 変数と関数にはキャメルケースを使用する

• クラスとインターフェースにはパスカルケースを使用する

• JSDocコメントによるドキュメント関数

• 行の長さは100文字以下にしてください

プロジェクト構造

プロジェクトは次の構造に従います。

プルリクエストプロセス

1. コードがスタイルガイドラインに従っていることを確認する

2. 必要に応じてドキュメントを更新する

3. 新しい機能のテストを追加する

4. すべてのテストに合格することを確認する

5. あなたのPRはメンテナーによってレビューされます

関連リンク

• モデルコンテキストプロトコル

• Spotify Web API ドキュメント

• クロードデスクトップ

ライセンス

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