Spotify Bulk Actions Mcp

Spotify 批量操作 MCP

用于 Spotify 批量操作的模型上下文协议（MCP）服务——批量创建播放列表、导出曲库，以及大规模管理曲库。

它与其他 Spotify MCP 有何不同？

• 置信度评分——批量搜索会为每个匹配结果返回 HIGH/MEDIUM/LOW 置信度
• 人工参与流程——不确定的匹配结果会导出供人工审核，之后再重新导入
• 批量操作——高效处理 500 首以上的歌曲，内置速率限制
• 曲库导出——导出完整的曲库数据
• 专注于播客播放列表——专为从播客节目备注中导入歌曲列表而构建

---

支持此项目

开发这个项目是因为我离不开耳机，想管理我订阅的 8 万多个播客。支持我：

---

收录于

目录	链接
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 等播客播放列表

---

功能介绍

曲库分析：

• 获取所有已关注的艺人
• 获取所有已保存/点赞的歌曲（支持多达 1 万首歌曲的曲库）
• 按歌曲数量排名，查找曲库中不重复的艺人
• 查找已保存歌曲数量达到 6 首及以上的专辑（非常适合挑选黑胶唱片！）
• 导出完整的曲库摘要

收听洞察：

• 收听次数最多的艺人和曲目（短期/中期/长期）
• 最近播放记录

批量创建播放列表：

• 从 CSV 文件导入歌曲列表（用于播客播放列表等）
• 按置信度评分进行批量搜索（HIGH/MEDIUM/LOW）
• 自动处理不确定的匹配结果，以供人工审核
• 根据搜索结果创建播放列表

播放列表维护：

• 查找并移除重复曲目
• 比较两个播放列表（共有曲目与各自独有的曲目）
• 批量移除和重新排序曲目，更新播放列表详情
• 将任意播放列表导出为 CSV

曲库批量操作：

• 批量关注/取消关注艺人
• 批量保存/取消保存曲目

快速开始

1. 前置条件

• Python 3.10+
• Spotify 账号
• Spotify 开发者凭据（在此获取）

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 服务运行（MCP_TRANSPORT=http）， 前置 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	搜索单首曲目
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	获取播放列表详情
update_playlist	更新名称、描述和公开状态
get_playlist_tracks	获取播放列表中的所有曲目
export_playlist_to_csv	将播放列表导出为 CSV
compare_playlists	比较两个播放列表中的共有和独有曲目
find_duplicate_tracks	查找播放列表中的重复曲目
remove_duplicate_tracks	移除重复曲目，并保留首次出现的曲目
remove_tracks_from_playlist	批量移除指定曲目
reorder_playlist_tracks	调整播放列表中曲目的顺序

实用工具

工具	描述
parse_song_list_csv	验证歌曲 CSV
export_review_csv	导出不确定的匹配项以供审核

与 Spotify 官方连接器的区别

Claude 有一个由 Spotify 于 2026 年 4 月构建的官方 Spotify 连接器。它在自身功能方面表现出色，但提供的工具种类不多；这个 MCP 则涵盖了它未涉及的功能。截至 2026 年 8 月，官方连接器提供 8 个工具：搜索 Spotify、创建播放列表、获取当前播放内容、添加到媒体库、从媒体库移除、获取播放列表曲目，以及两个身份验证工具。

功能	官方连接器	此 MCP
搜索、播放上下文、情绪播放列表	✅	仅搜索
创建播放列表	✅	✅（另支持 CSV 导入和置信度评分）
添加／移除已点赞歌曲	✅（一次一首）	✅ 批量操作
读取完整媒体库（已保存曲目、关注的艺人）	❌	✅
收听洞察（最常听的艺人／曲目、最近播放）	❌	✅
编辑现有播放列表（批量移除、调整顺序、更新详情）	❌	✅
去重／比较／将播放列表导出为 CSV	❌	✅
批量关注／取消关注艺人	❌	✅

还有一点不同：官方连接器运行在 Spotify 的合作伙伴专用 MCP 网关上（不支持动态客户端注册；普通开发者应用获取的令牌会被拒绝），因此只能在合作伙伴提供的 AI 平台中使用。此 MCP 使用你自己的 Spotify 开发者应用运行——开发模式限制仍然适用（截至 2026 年 2 月，每个 Client ID 最多允许 5 位用户），但你可以全程自行掌控。

示例工作流

获取你的资料库统计信息

询问 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 错误时自动重试
• 使用缓存减少重复调用

对于 10k 首歌曲，首次获取资料库预计需要 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 控制台中轮换凭据

许可证

MIT

---

制作这个是因为我离不开耳机。如果这对你有帮助，请给我买杯咖啡！