MCP クロード Spotify

特徴

Spotify認証
トラック、アルバム、アーティスト、プレイリストを検索
再生コントロール（再生、一時停止、次、前）
プレイリストの作成と管理
パーソナライズされたおすすめ情報を入手
さまざまな期間にわたってユーザーが最もよく再生したトラックにアクセスします

デモ

要件

Node.js 16以上
Spotifyアカウント
クロードデスクトップ
Spotify API 資格情報 (クライアント ID とクライアントシークレット)

インストール

Smithery経由でインストール

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

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

手動でインストールする

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

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

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

npm install

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

npm run build

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

Spotify認証情報の設定

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

Spotify開発者ダッシュボードへ
Spotifyアカウントでログイン
「アプリを作成」をクリックします
アプリ情報を入力してください:
- アプリ名:「MCP Claude Spotify」（またはお好きな名前）
- アプリの説明: 「Claude Desktop 向け Spotify 統合」
- ウェブサイト: 空白のままにするか、任意のURLを入力してください
- リダイレクトURI:重要- http://127.0.0.1:8888/callbackを追加
利用規約に同意して「作成」をクリックします
アプリのダッシュボードに「クライアントID」が表示されます。
「クライアントシークレットを表示」をクリックすると「クライアントシークレット」が表示されます。

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

MCPサーバーの実行

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

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

ターミナルまたはコマンドプロンプトを開きます
プロジェクトディレクトリに移動する
サーバーを直接実行します。

node build/index.js

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

{
  "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 から取得したクライアント ID です
your_client_secret_hereに Spotify から取得したクライアントシークレットを入力します。

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

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

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

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

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

このBATファイルへのショートカットを作成します
Win+Rを押して、 shell:startupと入力してEnterを押します。
このフォルダにショートカットを移動すると、Windows で起動するようになります。
~/Library/LaunchAgents/に次の内容を含むcom.spotify.mcp.plistという名前のファイルを作成します。

<?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>

パスと資格情報を実際の値に置き換えます
エージェントをロードするには、 launchctl load ~/Library/LaunchAgents/com.spotify.mcp.plist
~/.config/systemd/user/にspotify-mcp.serviceという名前のファイルを作成します (ディレクトリが存在しない場合は作成します)。

[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

使用法

設定を変更した後、Claude Desktopを再起動します。
Claudeでは、 auth-spotifyコマンドを使用して認証プロセスを開始します。
アプリケーションを承認するためのブラウザウィンドウが開きます
Spotifyアカウントでログインし、アプリケーションを承認します
重要: 認証が成功したら、Claude Desktopを再起動して、MCPのツールレジストリとWebSocketセッショントークンキャッシュを適切に初期化します。
再起動後、すべての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: サーバーが切断されました」というエラーが表示される場合:

サーバーが実行中であることを確認します:
- ターミナルを開き、プロジェクトディレクトリからnode build/index.js手動で実行します。
- サーバーが正常に起動したら、このターミナルを開いたままClaudeを使用します。
設定を確認してください:
- claude_desktop_config.jsonの絶対パスがシステムに合っていることを確認してください
- Windowsのパスに二重のバックスラッシュ（ \\ ）を使用していることを確認してください
- ファイルシステムのルートからの完全なパスを使用していることを確認してください
自動起動オプションを試してください:
- 「自動起動スクリプトの設定」セクションの説明に従って、オペレーティングシステムの自動起動スクリプトを設定します。
- これにより、必要なときにサーバーが常に実行されるようになります。

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

認証中にブラウザが自動的に開かない場合は、手動でアクセスしてください: 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 サーバー機能 - ツールの適切な登録と実行を保証します

テストの実行

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

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 サーバー機能のテスト

新しいテストの追加

新しい機能を追加するときは、対応するテストを含めてください。

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

すべてのテストは、Jest と TypeScript を使用した ESM モジュール形式を使用して記述する必要があります。

セキュリティノート

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

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

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

この統合はもう使用していません
不正アクセスが疑われる
認証の問題をトラブルシューティングしています

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

Spotifyアカウントページに移動します
メニューの「アプリ」に移動します
「MCP Claude Spotify」（またはアプリに付けた名前）を見つけます
「アクセスを削除」をクリックします

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

貢献

貢献を歓迎します！以下のガイドラインに従ってください。

開発ワークフロー

リポジトリをフォークする
機能ブランチを作成する ( git checkout -b feature/amazing-feature )
変更を加える
テストを実行して合格することを確認する ( npm test )
変更をコミットします ( git commit -m 'Add some amazing feature' )
ブランチにプッシュする ( git push origin feature/amazing-feature )
プルリクエストを開く

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

このプロジェクトは次のコーディング標準に従います。

厳密な型チェックを備えたTypeScriptを使用する
ESMモジュール形式に従う
インデントには2つのスペースを使用します
変数と関数にはキャメルケースを使用する
クラスとインターフェースにはパスカルケースを使用する
JSDocコメントによるドキュメント関数
行の長さは100文字以下にしてください

プロジェクト構造

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

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

プルリクエストプロセス

コードがスタイルガイドラインに従っていることを確認する
必要に応じてドキュメントを更新する
新しい機能のテストを追加する
すべてのテストに合格することを確認する
あなたのPRはメンテナーによってレビューされます

ライセンス

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

Integrations

MCP クロード Spotify

特徴

デモ

要件

インストール

Smithery経由でインストール

手動でインストールする

Spotify認証情報の設定

MCPサーバーの実行

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

オプション 2: Claude Desktop で自動起動 (通常の使用に推奨)

構成

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

使用法

利用可能なツール

認証-Spotify

Spotifyで検索

再生トラック

現在の再生を取得

一時停止-再生

次のトラック

前のトラック

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

プレイリストを作成

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

推奨事項を取得する

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

トラブルシューティング

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

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

認証エラー

サーバー起動エラー

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

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

テスト

テストの実行

テスト構造

新しいテストの追加

セキュリティノート

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

貢献

開発ワークフロー

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

プロジェクト構造

プルリクエストプロセス

関連リンク

ライセンス