spotify-mcp

一个 MCP 服务器，封装了 spotipy，使 Claude（或任何 MCP 客户端）能够搜索 Spotify 并读取播放列表、已保存的曲目、艺术家目录和发现信号。

专门作为 re-com 的 Spotify 后端构建——设计上以读取为主，不是播放控制服务器。它确实支持创建播放列表并向其中添加曲目（因此 re-com 的推荐列表可以变成真正的播放列表），但没有播放/暂停/队列控制；请查看已有的几个专注于播放的 Spotify MCP 服务器。

工具

一个真实的限制，直说： Spotify 对 2024 年 11 月之后创建且未获得“扩展配额模式”（Spotify 很少授予的手动批准）的 API 应用限制 /recommendations 和 artist_related_artists。如果你的应用没有该模式，get_recommendations 和 get_related_artists 将返回 403——handle_errors 会将其转换为清晰的消息，而不是原始回溯，并且 re-com 的 spotify_client.py 将其视为一个信号不可用，而不是致命错误。search_music、播放列表、已保存曲目和艺术家热门曲目不受影响。

此机器上的其他 Claude Code 项目（例如 re-com）通过 MCP 启动此服务器来调用这些工具，而不是直接与 spotipy/Spotify 通信——这是唯一存放 Spotify 凭据的地方。

设置

1. 注册 Spotify 应用

1. 前往 Spotify 开发者仪表板，创建一个应用。

2. 添加与 SPOTIFY_REDIRECT_URI 匹配的重定向 URI（默认为 http://127.0.0.1:8888/callback——你不需要在该端口上实际监听任何内容；请参阅步骤 3）。

3. 记下应用的客户端 ID 和客户端密钥。

2. 安装依赖

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

3. 进行身份验证

export SPOTIFY_CLIENT_ID="..."
export SPOTIFY_CLIENT_SECRET="..."
python scripts/setup_auth_spotify.py

这会打印一个授权 URL，等待你登录并粘贴你被重定向到的 URL（在 SSH/无头环境下也能正常工作——无需绑定重定向端口），并将生成的令牌写入 .spotify_cache（路径可通过 SPOTIFY_CACHE_PATH 配置）。

.spotify_cache 等同于你的登录会话——切勿提交或分享它。 它已被 gitignore。令牌一旦缓存就会自动刷新；仅当刷新本身开始失败（例如应用的客户端密钥被轮换，或你从 Spotify 账户设置中撤销了访问权限）或 server.py 中的 SCOPE 获得新权限时，才重新运行此脚本（先删除 .spotify_cache，以便授权流程重新提示同意——过期的缓存令牌不会自行获取新范围）。

4. 添加到 Claude Code

claude mcp add spotify -s user \
  -e SPOTIFY_CLIENT_ID="..." \
  -e SPOTIFY_CLIENT_SECRET="..." \
  -e SPOTIFY_CACHE_PATH="$(pwd)/.spotify_cache" \
  -- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"

-s user 使其在任何 Claude Code 会话中可用，而不仅仅是此目录。对 python 解释器、server.py 和 SPOTIFY_CACHE_PATH 使用绝对路径，因为服务器可以从任何工作目录启动。

对于其他 MCP 客户端（Claude Desktop 等），使用它们各自的配置格式，将它们指向相同的命令和环境变量。

测试

单元测试套件（tests/）针对手写的假 spotipy.Spotify 客户端运行——无需网络访问或 Spotify 凭据：

pip install -e ".[dev]"
pytest

错误处理

工具调用将常见故障模式转换为清晰的消息，而不是原始回溯：

• 缺少/过期的身份验证（401）→ 提示你重新执行 身份验证步骤。

• 受限/禁止（403）→ 提示你可能是 Spotify API 访问限制（请参阅上面的推荐/相关艺术家注意事项）或缺少 OAuth 范围。

• 速率限制（429）→ 提示你等待，包括 Spotify 发送的 Retry-After 提示（如果有）。

• 任何其他 API 或 OAuth 错误都会直接报告，而不是作为原始回溯。

许可证

MIT — 请参阅 LICENSE。