Spotify Bulk Actions Mcp

Spotify Bulk Actions MCP

Spotify の一括操作に対応した Model Context Protocol（MCP）サーバーです。プレイリストの一括作成、ライブラリのエクスポート、大規模なライブラリ管理を実行できます。

ほかの Spotify MCP と異なる点は？

• 信頼度スコア - 一括検索では、各候補に HIGH／MEDIUM／LOW の信頼度が付与されます
• 人間による確認 - 不確かな候補をエクスポートして確認し、その後再インポートできます
• 一括操作 - レート制限機能を備え、500 曲以上を効率的に処理します
• ライブラリのエクスポート - ライブラリの全データをエクスポートできます
• ポッドキャストのプレイリストに特化 - ポッドキャストの番組ノートにある曲リストをインポートするために開発されました

---

このプロジェクトを支援する

ヘッドフォンを常に着けているために作りました。80k+ のポッドキャスト登録を支援してください。

---

掲載先

ディレクトリ	リンク
PyPI	pypi.org/project/spotify-bulk-actions-mcp
mcp.so	mcp.so/server/spotify-bulk-actions-mcp
awesome-mcp-servers	PR #1541 (保留中)

---

これを使って作成したプロジェクト

プロジェクト	説明	リンク
recordOS	いちばん好きなアルバムはどれですか？ビジュアルで楽しめるアルバムコレクションアプリ	公開版 · リポジトリ
Festival Navigator	友人と一緒に複数日にわたるフェスティバルを巡りましょう	リポジトリ

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

近日公開：Switched On Pop、This American Life などのポッドキャストプレイリスト

---

このサーバーでできること

ライブラリ分析：

• フォローしているアーティストをすべて取得
• 保存済み／「いいね」した曲をすべて取得（最大 10k 曲のライブラリに対応）
• ライブラリ内のユニークなアーティストを曲数順に検索
• 保存済みの曲が 6 曲以上あるアルバムを検索（レコード購入に最適です！）
• ライブラリの完全な概要をエクスポート

リスニングインサイト：

• 上位のアーティストとトラック（短期／中期／長期）
• 最近再生した履歴

プレイリストの一括作成：

• CSV ファイルから曲リストをインポート（ポッドキャストのプレイリストなど）
• 信頼度スコア付きの一括検索（HIGH／MEDIUM／LOW）
• 不確かな候補を自動的に処理し、人間による確認に回します
• 検索結果からプレイリストを作成

プレイリストのメンテナンス：

• 重複トラックを検索して削除
• 2 つのプレイリストを比較（共通トラックと固有トラック）
• トラックの一括削除と並べ替え、プレイリストの詳細の更新
• 任意のプレイリストを CSV にエクスポート

ライブラリの一括操作：

• アーティストの一括フォロー／フォロー解除
• トラックの一括保存／保存解除

クイックスタート

1. 前提条件

• Python 3.10+
• Spotify アカウント
• Spotify Developer の認証情報（こちらで取得）

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

# Clone the repo
git clone https://github.com/khglynn/spotify-bulk-actions-mcp.git
cd spotify-bulk-actions-mcp

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the package
pip install -e .

# Copy env example and add your credentials
cp .env.example .env
# Edit .env with your SPOTIFY_CLIENT_ID and 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 spotify_bulk_actions_mcp.utils.auth import is_authenticated; print('Auth OK!' if is_authenticated() else 'Not authenticated')"

オプション B：ホスト型（claude.ai カスタムコネクター）

このサーバーはストリーミング可能な HTTP（MCP_TRANSPORT=http）経由のリモート MCP としても動作し、 OAuth 2.1（WorkOS AuthKit）と、フェイルクローズ方式のユーザー許可リストで保護されています。作成者は Cloud Run と Secret Manager を使って Spotify のリフレッシュトークンを管理し、 claude.ai にカスタムコネクターとして追加して運用しています。ツールには readOnlyHint／destructiveHint アノテーションが付与されているため、クライアントは読み取り操作と書き込み操作を分類できます。Dockerfile と 親コレクションリポジトリのデプロイ手順を参照してください。

5. Claude Code に接続する

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

{
  "mcpServers": {
    "spotify": {
      "command": "/path/to/spotify-bulk-actions-mcp/venv/bin/spotify-bulk-actions-mcp"
    }
  }
}

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

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

ライブラリの分析

ツール	説明
check_auth_status	Spotify の認証が機能していることを確認します
get_followed_artists	フォローしているすべてのアーティストを取得します
get_saved_tracks	いいねしたすべての曲を取得します
get_library_artists	保存した曲に含まれるアーティストを、件数順に取得します
get_albums_by_song_count	保存した曲が N 曲以上あるアルバムを取得します
export_library_summary	ライブラリ全体をエクスポートします

リスニングインサイト

ツール	説明
get_top_artists	トップアーティストを取得します（短期／中期／長期）
get_top_tracks	トップトラックを取得します（短期／中期／長期）
get_recently_played	最近再生したトラックを取得します

ライブラリの一括操作

ツール	説明
follow_artists	アーティストを一括でフォローします
unfollow_artists	アーティストのフォローを一括解除します
save_tracks	トラックを一括でいいね／保存します
unsave_tracks	トラックのいいね／保存を一括解除します

検索

ツール	説明
search_track	1 曲を検索します
search_track_fuzzy	完全一致で見つからない場合に、より広範囲に検索します
batch_search_tracks	信頼度スコア付きで複数のトラックを検索します
get_track_preview_url	30 秒のプレビュー URL を取得します

プレイリストの作成

ツール	説明
create_playlist	新しいプレイリストを作成します
add_tracks_to_playlist	既存のプレイリストにトラックを追加します
import_and_create_playlist	CSV のインポートからプレイリスト作成までを実行します
create_playlist_from_search_results	一括検索の結果からプレイリストを作成します
add_reviewed_tracks	確認・修正済みのトラックを追加します

プレイリストの管理

ツール	説明
get_playlist_info	プレイリストの詳細を取得します
update_playlist	名前、説明、公開状態を更新します
get_playlist_tracks	プレイリスト内のすべてのトラックを取得します
export_playlist_to_csv	プレイリストを CSV にエクスポートします
compare_playlists	2 つのプレイリスト間で、共通するトラックと固有のトラックを比較します
find_duplicate_tracks	プレイリスト内の重複トラックを見つけます
remove_duplicate_tracks	最初の出現を残して、重複を削除します
remove_tracks_from_playlist	指定したトラックを一括削除します
reorder_playlist_tracks	プレイリスト内のトラックの順序を変更します

ユーティリティ

ツール	説明
parse_song_list_csv	曲の CSV を検証します
export_review_csv	確信度の低い一致を確認用にエクスポートします

Spotify 公式コネクターとの違い

Claude には Spotify が開発した公式 Spotify コネクター（2026 年 4 月公開）があります。対応する機能は優れていますが、提供するツールは少なく、この MCP は公式コネクターではカバーされない機能をすべて提供します。2026 年 8 月時点で、公式コネクターが提供するツールは 8 つです。Spotify を検索、プレイリストを作成、再生中の曲を取得、ライブラリに追加、ライブラリから削除、プレイリスト内のトラックを取得する機能と、認証ユーティリティ 2 つです。

機能	公式コネクター	この MCP
検索、再生状況、ムード別プレイリスト	✅	検索のみ
プレイリストの作成	✅	✅（信頼度スコア付きの CSV インポートも可能）
いいねした曲の追加／削除	✅（一度に 1 曲）	✅ 一括操作
ライブラリ全体の読み込み（保存したトラック、フォロー中のアーティスト）	❌	✅
リスニングインサイト（トップアーティスト／トラック、最近再生した曲）	❌	✅
既存プレイリストの編集（一括削除、順序変更、詳細の更新）	❌	✅
プレイリストの重複排除／比較／CSV エクスポート	❌	✅
アーティストの一括フォロー／フォロー解除	❌	✅

もう 1 つの違いは、公式コネクターが Spotify のパートナー限定 MCP ゲートウェイで実行されることです（動的なクライアント登録には対応しておらず、通常の開発者アプリのトークンは拒否されます）。そのため、提携している AI サービス内でしか利用できません。この MCP は独自の Spotify 開発者アプリ上で動作します。開発モードには制限があります（2026 年 2 月時点で、クライアント ID ごとに許可リストへ登録できるユーザーは 5 人）が、すべてを自分で管理できます。

ワークフローの例

ライブラリの統計情報を確認する

Claude に質問します：

「保存している曲が最も多いアーティストは誰ですか？」

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

レコード用のアルバムを探す

Claude に質問します：

「保存している曲が6曲以上あるアルバムを探してください」

Claude は min_songs=6 を指定して get_albums_by_song_count を使用します。

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

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. 曲リストを使って batch_search_tracks を実行するよう Claude に依頼します
2. 結果を確認します（信頼度が高い曲は自動的に追加されます）
3. export_review_csv を使って不確かな一致候補を取得します
4. スプレッドシートで確認・修正します
5. add_reviewed_tracks を使って修正した曲を追加します

レート制限

サーバーは Spotify のレート制限に自動的に対応します：

• API 呼び出しの間に短い待機を入れます
• 429 エラーが発生すると自動的に再試行します
• 繰り返しの呼び出しを減らすためにキャッシュします

1万曲の場合、最初のライブラリ取得には2～3分かかります。

ファイルとデータ

場所	用途
.env	Spotify の認証情報（gitignore 対象）
.spotify_cache/	認証トークンとキャッシュデータ（gitignore 対象）
spotify_bulk_actions_mcp/server.py	メインの MCP サーバー
spotify_bulk_actions_mcp/tools/	ツールの実装

トラブルシューティング

「認証されていません」エラー：

python setup_auth.py

レート制限エラー： 数分待ってから、もう一度お試しください。サーバーは自動的に再試行します。

トークンの有効期限切れ： サーバーはトークンを自動更新します。問題が解決しない場合は、setup_auth.py を再実行してください。

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

• 認証情報は .env に保存されます（gitignore 対象で、コミットされることはありません）
• 認証トークンはローカルの .spotify_cache/ に保存されます
• .env ファイルやトークンファイルを共有しないでください
• 認証情報が漏えいした場合は、Spotify Dashboard で認証情報をローテーションしてください

ライセンス

MIT

---

ヘッドホンを着けずにはいられないので作りました。お役に立てたら、コーヒーをおごってください！