spotify-mcp

spotify-mcp

与 AI 对话即可控制 Spotify。适用于 Claude Desktop、Claude Code、 Cursor 及其他 MCP 客户端的 MCP 服务。

你： 播放一些早期 Bill Evans 的作品 AI： ▶ 正在播放：“Peace Piece” — Bill Evans · Everybody Digs Bill Evans

你： 太棒了，把整张专辑加入队列，并保存这首歌 AI： ➕ 已将 Everybody Digs Bill Evans 加入队列 · ❤️ 已将“Peace Piece”保存到你的音乐库

基于当前（2026 年 2 月之后）的 Spotify Web API 构建——许多较早的 Spotify MCP 服务早于这些改动，因此部分功能已无法正常使用。

要求

• Spotify Premium——Spotify 要求使用 Premium 才能控制播放；自 2026 年 2 月起，创建你将使用的开发者应用也需要 Premium。
• Node.js ≥ 20

快速开始

npx -y @xavifabregat/spotify-mcp init

向导将引导你创建自己的（免费）Spotify 开发者应用，询问其 Client ID，并打开浏览器连接你的账户——全程约 2 分钟。

为什么要使用自己的应用？Spotify 将第三方应用的用户数限制在少数几人，因此每位用户都需要使用自己的应用；向导让这一过程变得轻松。无需 Client Secret（使用 PKCE）。令牌保存在你设备上的 ~/.spotify-mcp/ 中，并会静默刷新。

唯一必须准确填写的信息——应用的 Redirect URI：

http://127.0.0.1:8888/callback

添加到 MCP 客户端

Claude Code

claude mcp add -s user spotify -- npx -y @xavifabregat/spotify-mcp

Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json） 或 Cursor（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "spotify": {
      "command": "npx",
      "args": ["-y", "@xavifabregat/spotify-mcp"]
    }
  }
}

重启客户端，然后开始对话。

工具

工具	功能
play	通过自由文本查询（搜索 → 最佳匹配 → 播放）或 Spotify URI 播放
playback	暂停 / 恢复 / 下一首 / 上一首 / 跳转 / 音量 / 随机播放 / 循环播放
now_playing	当前曲目、播放进度、设备、模式
queue	将曲目加入队列；显示下一首播放的内容
devices	列出设备；转移播放
search	浏览曲目 / 专辑 / 艺人 / 播放列表（每种类型最多 10 个——API 限制）
get_playlists	列出你的播放列表
get_playlist_items	显示播放列表中的曲目（仅限自有或协作播放列表——API 限制）
modify_playlist	创建播放列表；添加曲目
library	在你的音乐库中保存 / 移除 / 检查项目
authenticate	在对话中运行 Spotify 登录流程

设计

• 工具代表意图，而非 API 端点。“播放一些 Radiohead”只需一次工具调用—— 服务会搜索、挑选最佳匹配、开始播放，并告知你选择了什么，以便你进行更正。无需经历搜索 → 选择 → 播放的多轮往返。
• 接口精简。 使用 11 个工具，而不是为每个 API 端点配置一个工具，因此在不同 AI 客户端中都能准确选择工具，并保持上下文精简。
• 响应是包含 Spotify URI 的简洁文本，因此后续请求（“把那首加入队列”）可以接续处理，无需重新搜索。原始 API 负载不会传给模型。
• 错误会提供操作指引。 没有活动设备？响应会列出你的设备，并说明如何选择。尚未登录？响应会提示使用 authenticate 工具。模型会转述解决方法，而不是堆栈跟踪。

故障排查

• “没有活跃的 Spotify 设备” — Spotify 的 API 只能控制正在运行的应用。请在任意设备上打开 Spotify；如果它刚刚唤醒，请点按一次播放/暂停。只有一台设备在线时， 工具会自动将其作为目标设备。
• 登录时出现 INVALID_CLIENT: Invalid redirect URI — 应用设置中的重定向 URI 必须与 http://127.0.0.1:8888/callback 完全一致（Spotify 不接受 localhost）。
• 登录时端口 8888 被占用 — 将 SPOTIFY_REDIRECT_PORT 设置为一个空闲端口，并 注册匹配的重定向 URI。
• “令牌刷新失败” — 运行 npx -y @xavifabregat/spotify-mcp auth 重新登录 （例如，更改 Client ID 后）。
• 配置优先级 — SPOTIFY_CLIENT_ID 环境变量的优先级高于 ~/.spotify-mcp/config.json（由 init 写入）。

开发

git clone https://github.com/XavierFabregat/spotify-mcp.git
cd spotify-mcp
npm install
npm run build
npm run inspect   # MCP Inspector against the local build

目录结构：src/auth.ts（OAuth PKCE + 令牌存储）· src/spotify.ts（类型化 API 客户端）· src/tools/（工具实现）· src/format.ts（精简输出）。

许可证

MIT © Xavi Fabregat