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 开发者控制台中更新它们