Spotify Bulk Actions MCP

🚀 Spotify Bulk Actions MCP

Spotifyの一括操作を行うためのModel Context Protocol (MCP)サーバーです。バッチでのプレイリスト作成、ライブラリエクスポート、大規模なライブラリ管理が可能です。

🚀 クイックスタート

1. 前提条件

• Python 3.10以上
• Spotifyアカウント
• Spotify Developerの認証情報（ここから取得）

2. クローンとセットアップ

# リポジトリをクローン
git clone https://github.com/khglynn/spotify-bulk-actions-mcp.git
cd spotify-bulk-actions-mcp

# 仮想環境を作成してアクティブ化
python -m venv venv
source venv/bin/activate  # Windowsの場合: venv\Scripts\activate

# パッケージをインストール
pip install -e .

# 環境変数のサンプルファイルをコピーし、認証情報を追加
cp .env.example .env
# .envファイルを編集し、SPOTIFY_CLIENT_IDとSPOTIFY_CLIENT_SECRETを設定

PyPIでも利用可能です: pip install spotify-bulk-actions-mcp - ただし、ローカルの.envファイルと認証設定が必要です。

3. Spotifyでの認証（一度だけ）

これによりブラウザが開き、ログインできます。

python setup_auth.py

ログイン後、トークンは.spotify_cache/にローカルに保存されます。

4. 動作確認

source venv/bin/activate
python -c "from src.utils.auth import is_authenticated; print('Auth OK!' if is_authenticated() else 'Not authenticated')"

5. Claude Codeへの接続

Claude Codeの設定ファイル（~/.claude/settings.local.json）に以下を追加します。

{
  "mcpServers": {
    "spotify": {
      "command": "/path/to/spotify-bulk-actions-mcp/venv/bin/python",
      "args": ["/path/to/spotify-bulk-actions-mcp/src/server.py"]
    }
  }
}

追加後、Claude Codeを再起動します。

✨ 主な機能

• 信頼度スコアリング - バッチ検索では、各マッチに対してHIGH/MEDIUM/LOWの信頼度が返されます。
• 人間によるレビュー - 不確かなマッチはレビュー用にエクスポートされ、再インポートされます。
• 一括操作 - レート制限を組み込んで、500曲以上の曲を効率的に処理します。
• ライブラリエクスポート - 完全なライブラリデータをエクスポートします。
• ポッドキャストプレイリストに特化 - ポッドキャストのショーノートからの曲リストのインポートに特化して構築されています。

📦 インストール

前提条件とクイックスタートの手順に従ってインストールしてください。

💻 使用例

基本的な使用法

ライブラリの統計情報を取得する

Claudeに以下のように問いかけます。

"最も多くの保存曲を持っているアーティストは誰ですか？"

Claudeはget_library_artistsを使用して結果を表示します。

ビニール用のアルバムを検索する

Claudeに以下のように問いかけます。

"保存曲が6曲以上あるアルバムを検索してください"

Claudeはget_albums_by_song_countをmin_songs=6で使用します。

曲リストからプレイリストを作成する

1. CSVファイルを作成します。

title,artist
Bohemian Rhapsody,Queen
Hotel California,Eagles
Billie Jean,Michael Jackson

2. Claudeに以下のように問いかけます。

"このCSVから 'My Mix' という名前のプレイリストを作成してください: [CSVを貼り付け]"

Claudeは以下の操作を行います。

1. CSVを解析します。
2. 各曲を信頼度スコア付きで検索します。
3. 高信頼度のマッチでプレイリストを作成します。
4. 不確かなマッチを表示してレビューするように促します。

バルクポッドキャストプレイリストの作成

大規模なリスト（500曲以上）の場合:

1. Claudeにbatch_search_tracksを使用して曲リストを検索するように依頼します。
2. 結果をレビューします（HIGHのものは自動的に追加されます）。
3. export_review_csvを使用して不確かなマッチをエクスポートします。
4. スプレッドシートでレビュー/修正します。
5. add_reviewed_tracksを使用して修正した曲を追加します。

📚 ドキュメント

利用可能なツール（18個）

ライブラリ分析

検索

プレイリスト

ユーティリティ

リストされている場所

このMCPを使用して構築したプロジェクト

このMCPで管理されているプレイリスト

近日公開: Switched On Pop、This American Life、その他のポッドキャストプレイリスト

🔧 技術詳細

レート制限

サーバーはSpotifyのレート制限を自動的に処理します。

• API呼び出し間に小さな遅延を入れます。
• 429エラー時に自動的にリトライします。
• 繰り返しの呼び出しを減らすためにキャッシュを使用します。 10,000曲の場合、初期のライブラリ取得に2 - 3分かかることが予想されます。

ファイルとデータ

トラブルシューティング

"Not authenticated"エラー

python setup_auth.py

レート制限エラー

数分待ってから再度試してください。サーバーは自動的にリトライします。

トークンの期限切れ

サーバーは自動的にトークンを更新します。問題が解決しない場合は、setup_auth.pyを再度実行してください。

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

• あなたの認証情報は.envファイルに保存されています（gitignored、決してコミットされません）。
• 認証トークンは.spotify_cache/にローカルに保存されています。
• .envファイルやトークンファイルを決して共有しないでください。
• 認証情報が漏洩した場合は、Spotifyダッシュボードでローテーションしてください。

📄 ライセンス

MITライセンスです。

このプロジェクトは、私がヘッドフォンを外せないから作られました。もしこれがあなたに役立ったら、コーヒーを奢ってください!