Spotify Bulk Actions MCP

🚀 Spotify Bulk Actions MCP

Spotify Bulk Actions MCP 是一個用於 Spotify 批量操作的模型上下文協議（MCP）服務器，支持批量創建播放列表、導出音樂庫以及進行大規模的音樂庫管理。

✨ 主要特性

• 置信度評分：批量搜索會為每個匹配結果返回高/中/低置信度。
• 人工干預：不確定的匹配結果會導出供人工審核，之後再重新導入。
• 批量操作：內置速率限制，可高效處理 500 首以上的歌曲。
• 音樂庫導出：可導出完整的音樂庫數據。
• 專注於播客播放列表：專為從播客節目筆記中導入歌曲列表而設計。

📦 安裝指南

1. 前提條件

• Python 3.10 及以上版本
• 一個 Spotify 賬戶
• Spotify 開發者憑證（點擊獲取）

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。

💻 使用示例

基礎用法

以下是獲取音樂庫統計信息的示例： 向 Claude 提問：

"我收藏歌曲最多的藝術家有哪些？" Claude 將使用 get_library_artists 工具並展示結果。

高級用法

以下是從歌曲列表創建播放列表的示例：

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. 展示不確定的匹配結果供你審核

📚 詳細文檔

可用工具（共 18 個）

音樂庫分析

搜索

播放列表

實用工具

示例工作流程

獲取音樂庫統計信息

向 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. 審核結果（高置信度的結果會自動添加）
3. 使用 export_review_csv 工具導出不確定的匹配結果
4. 在電子表格中審核/修正
5. 使用 add_reviewed_tracks 工具添加修正後的歌曲

🔧 技術細節

速率限制

服務器會自動處理 Spotify 的速率限制：

• 在 API 調用之間設置小的延遲
• 遇到 429 錯誤時自動重試
• 使用緩存減少重複調用 對於 10000 首歌曲，首次獲取音樂庫預計需要 2 - 3 分鐘。

文件與數據

📄 許可證

本項目採用 MIT 許可證。

支持本項目

本項目因作者離不開耳機而誕生，旨在支持其 80000 多個播客訂閱。如果你覺得本項目對你有幫助，請作者喝杯咖啡吧！

項目發佈位置

使用本項目構建的其他項目

使用本 MCP 維護的播放列表

即將推出：Switched On Pop、This American Life 等播客播放列表。

故障排除

“未認證”錯誤

python setup_auth.py

速率限制錯誤

等待幾分鐘後重試，服務器會自動重試。

令牌過期

服務器會自動刷新令牌。如果問題仍然存在，請重新運行 setup_auth.py。

安全注意事項

• 你的憑證存儲在 .env 文件中（已添加到 .gitignore，不會提交）
• 認證令牌存儲在本地的 .spotify_cache/ 文件夾中
• 切勿分享你的 .env 或令牌文件
• 如果憑證洩露，請在 Spotify 開發者控制檯中更新它們