MCP Claude Spotify

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ファイルを参照してください。