spotify-mcp

spotipy をラップする MCP サーバーで、Claude（または任意の MCP クライアント）が Spotify を検索し、プレイリスト、保存済みトラック、アーティストのカタログ、ディスカバリーシグナルを読み取れるようにします。

re-com の Spotify バックエンドとして特別に構築されており、設計上読み取り重視で、再生制御サーバーではありません。プレイリストの作成やトラックの追加はサポートしています（re-com のレコメンデーションリストを実際のプレイリストにできるように）が、再生/一時停止/キューの制御はありません。そのような機能が必要な場合は、すでに存在する再生重視の Spotify MCP サーバーのいずれかをご覧ください。

ツール

明確に述べられた実際の制限: Spotify は、2024 年 11 月以降に作成され、「Extended Quota Mode」（Spotify が限定的に付与する手動承認）を持たない API アプリに対して、/recommendations と artist_related_artists を制限しています。アプリがこのモードを持っていない場合、get_recommendations と get_related_artists は 403 を返します — handle_errors はこれを生のトレースバックではなく明確なメッセージに変換し、re-com の spotify_client.py はこれを致命的なエラーではなく、1 つのシグナルが利用できないものとして扱います。search_music、プレイリスト、保存済みトラック、アーティストのトップトラックは影響を受けません。

このマシン上の他の Claude Code プロジェクト（例: re-com）は、これらのツールを呼び出す際、spotipy/Spotify に直接話しかけるのではなく、MCP 経由でこのサーバーを起動します — Spotify の認証情報が存在するのはこの場所だけです。

セットアップ

1. Spotify アプリを登録する

1. Spotify Developer Dashboard にアクセスし、アプリを作成します。

2. SPOTIFY_REDIRECT_URI に一致するリダイレクト URI を追加します（デフォルトは http://127.0.0.1:8888/callback — そのポートで実際に待ち受ける必要はありません。手順 3 を参照）。

3. アプリの Client ID と Client Secret をメモします。

2. 依存関係をインストールする

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

3. 認証する

export SPOTIFY_CLIENT_ID="..."
export SPOTIFY_CLIENT_SECRET="..."
python scripts/setup_auth_spotify.py

これにより認証 URL が表示され、ログインしてリダイレクト先の URL を貼り付けるのを待ちます（SSH/ヘッドレスでも問題なく動作します — リダイレクトポートをバインドする必要はありません）。結果のトークンは .spotify_cache に書き込まれます（パスは SPOTIFY_CACHE_PATH で設定可能）。

.spotify_cache はログイン中のセッションと同等です — 絶対にコミットしたり共有したりしないでください。 すでに gitignore されています。トークンはキャッシュされると自動的に更新されます。更新自体が失敗し始めた場合（アプリのクライアントシークレットがローテーションされた、Spotify アカウント設定からアクセスを失効させたなど）、または server.py の SCOPE に新しい権限が追加された場合にのみ、このスクリプトを再実行してください（新しいスコープは古いキャッシュ済みトークンでは自動的に取得されないため、認証フローが再同意を求めるように、先に .spotify_cache を削除してください）。

4. Claude Code に追加する

claude mcp add spotify -s user \
  -e SPOTIFY_CLIENT_ID="..." \
  -e SPOTIFY_CLIENT_SECRET="..." \
  -e SPOTIFY_CACHE_PATH="$(pwd)/.spotify_cache" \
  -- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"

-s user を指定すると、このディレクトリだけでなく、任意の Claude Code セッションで利用可能になります。サーバーは任意の作業ディレクトリから起動できるため、python インタープリタ、server.py、SPOTIFY_CACHE_PATH には絶対パスを使用してください。

他の MCP クライアント（Claude Desktop など）の場合は、それぞれの設定形式で同じコマンドと環境変数を指定してください。

テスト

単体テストスイート（tests/）は、手作りのフェイク spotipy.Spotify クライアントに対して実行されます — ネットワークアクセスや Spotify の認証情報は不要です:

pip install -e ".[dev]"
pytest

エラーハンドリング

ツール呼び出しは、一般的な失敗モードを生のトレースバックではなく明確なメッセージに変換します:

• 認証情報の欠落/期限切れ（401）→ 認証手順 をやり直すように指示します。

• 制限/禁止（403）→ Spotify API のアクセス制限（上記のレコメンデーション/関連アーティストの注意事項を参照）または OAuth スコープの欠落が原因である可能性が高いと伝えます。

• レート制限（429）→ Spotify が Retry-After ヒントを送信した場合はそれを含めて、待つように指示します。

• その他の API または OAuth エラーは、生のトレースバックではなく直接報告されます。

ライセンス

MIT — LICENSE を参照してください。