JinDaGe - spotify-bulk-actions-mcp MCP Details

article

README

🚀 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 工具并展示结果。

高级用法

以下是从歌曲列表创建播放列表的示例：

创建一个 CSV 文件：

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

向 Claude 提问：

"从这个 CSV 文件创建一个名为 'My Mix' 的播放列表：[粘贴 CSV 内容]" Claude 将执行以下操作：

解析 CSV 文件
对每首歌曲进行带置信度评分的搜索
使用高置信度匹配结果创建播放列表
展示不确定的匹配结果供你审核

📚 详细文档

可用工具（共 18 个）

音乐库分析

| 工具 | 描述 | |------|-------------| | check_auth_status | 验证 Spotify 认证是否正常工作 | | get_followed_artists | 获取你关注的所有艺术家 | | get_saved_tracks | 获取你所有喜欢的歌曲 | | get_library_artists | 按歌曲数量排名，获取收藏歌曲中的艺术家 | | get_albums_by_song_count | 获取收藏歌曲数量达到 N 首以上的专辑 | | export_library_summary | 导出完整的音乐库 |

搜索

| 工具 | 描述 | |------|-------------| | search_track | 搜索单首歌曲 | | search_track_fuzzy | 精确搜索失败时进行更广泛的搜索 | | batch_search_tracks | 对多首歌曲进行带置信度评分的搜索 | | get_track_preview_url | 获取歌曲 30 秒的预览链接 |

播放列表

| 工具 | 描述 | |------|-------------| | create_playlist | 创建一个新的播放列表 | | add_tracks_to_playlist | 向现有播放列表添加歌曲 | | import_and_create_playlist | 实现从 CSV 文件到播放列表的完整工作流程 | | create_playlist_from_search_results | 根据批量搜索结果创建播放列表 | | add_reviewed_tracks | 添加审核/修正后的歌曲 | | get_playlist_info | 获取播放列表的详细信息 |

实用工具

| 工具 | 描述 | |------|-------------| | parse_song_list_csv | 验证歌曲 CSV 文件 | | export_review_csv | 导出不确定的匹配结果供审核 |

示例工作流程

获取音乐库统计信息

向 Claude 提问：

"我收藏歌曲最多的艺术家有哪些？" Claude 将使用 get_library_artists 工具并展示结果。

查找适合黑胶唱片的专辑

向 Claude 提问：

"查找我收藏了 6 首或更多歌曲的专辑" Claude 将使用 get_albums_by_song_count 工具，设置 min_songs=6。

从歌曲列表创建播放列表

创建一个 CSV 文件：

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

向 Claude 提问：

"从这个 CSV 文件创建一个名为 'My Mix' 的播放列表：[粘贴 CSV 内容]" Claude 将执行以下操作：

解析 CSV 文件
对每首歌曲进行带置信度评分的搜索
使用高置信度匹配结果创建播放列表
展示不确定的匹配结果供你审核

批量创建播客播放列表

对于大型歌曲列表（500 首以上）：

让 Claude 使用 batch_search_tracks 工具处理你的歌曲列表
审核结果（高置信度的结果会自动添加）
使用 export_review_csv 工具导出不确定的匹配结果
在电子表格中审核/修正
使用 add_reviewed_tracks 工具添加修正后的歌曲

🔧 技术细节

速率限制

服务器会自动处理 Spotify 的速率限制：

在 API 调用之间设置小的延迟
遇到 429 错误时自动重试
使用缓存减少重复调用对于 10000 首歌曲，首次获取音乐库预计需要 2 - 3 分钟。

文件与数据

| 位置 | 用途 | |----------|---------| | .env | 存储你的 Spotify 凭证（已添加到 .gitignore，不会提交） | | .spotify_cache/ | 存储认证令牌和缓存数据（已添加到 .gitignore，不会提交） | | src/server.py | 主 MCP 服务器 | | src/tools/ | 工具实现代码 |

📄 许可证

本项目采用 MIT 许可证。

支持本项目

本项目因作者离不开耳机而诞生，旨在支持其 80000 多个播客订阅。如果你觉得本项目对你有帮助，请作者喝杯咖啡吧！

项目发布位置

| 平台 | 链接 | |-----------|------| | 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 等播客播放列表。

故障排除

“未认证”错误

python setup_auth.py

速率限制错误

等待几分钟后重试，服务器会自动重试。

令牌过期

服务器会自动刷新令牌。如果问题仍然存在，请重新运行 setup_auth.py。

安全注意事项

你的凭证存储在 .env 文件中（已添加到 .gitignore，不会提交）
认证令牌存储在本地的 .spotify_cache/ 文件夹中
切勿分享你的 .env 或令牌文件
如果凭证泄露，请在 Spotify 开发者控制台中更新它们

spotify-bulk-actions-mcp