SpotifyMCP

一个封装 Spotify Web API 的 MCP 服务器，让 AI 助手（如 Claude）能够控制播放、搜索包括播客和有声书在内的完整曲库、管理你的音乐库和播放列表，并理解你的收听品味。

为什么选择这个

大多数 Spotify MCP 服务器都只是薄封装。这个项目旨在成为默认选择：

• 完整的 API 覆盖 —— 所有使用标准开发者令牌即可调用的非弃用 Spotify Web API 端点都有对应的工具（播放、搜索、曲库、有声书、个性化、音乐库、播放列表、关注）。

• 对弃用功能诚实 —— Spotify 已从新应用中移除推荐、相关艺人、音频特征/分析、流派种子和精选播放列表。仍然暴露这些功能的服务器会提供在运行时必然失败的工具；本项目不会。

• 经过测试 —— 对客户端（令牌刷新、速率限制、分页）和每个工具处理器都有完整的单元测试套件，外加端到端的 MCP 协议冒烟测试。许多替代方案零测试。

• 全量分页 —— 音乐库和播放列表列表的 fetch_all 会遍历每一页（上限 500 条），而不是静默截断在每页 50 条的第一页。

• 播客是一等公民 —— 单集在所有地方都能用：正在播放、队列、搜索即播。几个竞品根本看不到播客。

• 设备感知的播放 —— 列出设备、转移播放，并将任何命令定向到特定设备，支持多房间设置。

• 健壮的身份验证 —— 带静默刷新的 PKCE 流程、持久化的 mode-600 令牌缓存、适用于服务器和容器的无头粘贴流程（SPOTIFY_HEADLESS=1）。

Related MCP server: Spotify MCP Server

功能特性

播放（15 个工具） —— 正在播放/当前播放轮询、播放（按 URI，或使用 play_from_search 直接按名称播放）、暂停、跳过、上一首、跳转、音量、随机播放、循环、队列查看/添加、设备列表、转移播放。

搜索与曲库 —— 跨曲目/艺人/专辑/播放列表/节目/单集的统一搜索；对曲目、艺人、艺人专辑、专辑、专辑曲目、节目、节目单集、单集以及你的个人资料（get_me）的深度查询。

有声书 —— 书名、章节、章节查询，以及你保存的有声书（受 Spotify 市场限制，仅限美国/英国/加拿大/爱尔兰/新西兰/澳大利亚）。

个性化 —— 三个时间范围内的热门曲目和艺人、最近播放。

音乐库 —— 已保存的曲目/专辑/节目/单集，支持可选的全量分页；通过 /me/library URI 统一保存/移除/检查。

播放列表 —— 完整的增删改查以及条目管理（添加/移除/重新排序）、封面图获取和自定义封面上传（上传需要 ugc-image-upload 权限范围）。

关注 —— 已关注艺人列表和关注状态检查。

此外还提供：7 个 MCP 资源（个人资料、播放器状态、队列、热门曲目/艺人、最近播放、播放列表）和 4 个提示模板（DJ 混音、心情播放列表、品味总结、发现替代）。

要求与限制

• 播放控制需要 Spotify Premium（播放、暂停、跳过、跳转、音量、随机播放、循环、队列、转移）。免费账户可以认证并使用搜索/曲库/音乐库/播放列表工具，但每个播放命令都会因 Spotify 返回需要 Premium 的错误而失败。

• fetch_all 分页每次调用最多遍历 500 条（防止失控循环）；超出后请使用 limit/offset 分页。

• 有声书工具受 Spotify 市场限制，仅限美国、英国、加拿大、爱尔兰、新西兰和澳大利亚。

• Spotify 开发者模式在获得扩展配额之前，每个应用最多允许 5 个授权用户。

快速设置

1. 创建 Spotify 应用

每个用户都需要自己的 Spotify 应用来获取 Client ID —— 这是 Spotify 识别哪个应用在发起 API 请求的方式。

1. 前往 Spotify 开发者仪表盘 并创建一个新应用。

2. 在应用设置中，精确添加以下 重定向 URI（如果不匹配，Spotify 将拒绝登录）：

   http://127.0.0.1:8888/callback

3. 保存。复制你的 Client ID。

2. 身份验证

运行下面的命令一次，登录你的 Spotify 账户。将 your_client_id_here 替换为第 1 步中的 Client ID。它会打开一个浏览器窗口，在你批准后，将令牌保存到 ~/.spotify-mcp/tokens.json。服务器会自动刷新它们 —— 你不需要再执行此操作。

macOS / Linux：

SPOTIFY_CLIENT_ID=your_client_id_here npx -y @novalux12/spotify-mcp@latest auth

无头 / 远程主机（运行 MCP 服务器的机器上没有浏览器）：

SPOTIFY_HEADLESS=1 SPOTIFY_CLIENT_ID=your_client_id_here npx -y @novalux12/spotify-mcp@latest auth

认证 URL 会被打印出来；在任何浏览器中完成流程（例如在你的笔记本电脑上），然后将重定向 URL 粘贴回提示符。适用于家庭实验室、CI 和代理运行时。

无头身份验证（无浏览器主机）

如果你在没有浏览器的宿主机上运行此 MCP 服务器 （例如云虚拟机、Docker 容器、远程服务器），请设置 SPOTIFY_HEADLESS=1 环境变量。认证流程将跳过 本地 HTTP 回调服务器，改为提示你在浏览器中 授权应用后粘贴重定向 URL。

步骤

1. 在你的环境中设置 SPOTIFY_HEADLESS=1

2. 运行服务器 —— 它会打印一个用于授权应用的 URL

3. 在另一台机器的浏览器中打开该 URL

4. 授权后，你的浏览器将重定向到重定向 URI

5. 从地址栏复制完整 URL

6. 将其粘贴回服务器提示符

原因

默认的认证流程通过 open 包打开浏览器，并在 127.0.0.1:8888 上运行本地 HTTP 回调服务器。当 MCP 服务器运行在无头宿主机（家庭实验室、CI、代理运行时）上时， 这就会失效，因为那里没有浏览器可供 open() 打开， 而且用户机器无法访问 127.0.0.1:8888 回调。

SPOTIFY_HEADLESS=1 切换到粘贴 URL 流程：认证 URL 打印到标准输出，操作员在任何浏览器（笔记本电脑、 手机）中完成流程，然后将完整的重定向 URL 粘贴回来。 代码 + 状态在服务端提取和交换。可跨机器工作。

Windows（命令提示符）：

set SPOTIFY_CLIENT_ID=your_client_id_here && npx -y @novalux12/spotify-mcp@latest auth

Windows（PowerShell）：

$env:SPOTIFY_CLIENT_ID="your_client_id_here"; npx -y @novalux12/spotify-mcp@latest auth

3. 配置 Claude Desktop

打开你的 claude_desktop_config.json：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows： 打开 Claude Desktop → 设置 → 开发者 → 编辑配置

添加 mcpServers 块（将 your_client_id_here 替换为你的 Client ID）：

{
  "mcpServers": {
    "spotify": {
      "command": "npx",
      "args": ["-y", "@novalux12/spotify-mcp@latest"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id_here"
      }
    }
  }
}

完全退出并重新启动 Claude Desktop。聊天输入框中的锤子图标确认服务器已连接。

替代方案：Claude Code

如果你使用 Claude Code，无需手动编辑 JSON 即可添加服务器：

claude mcp add spotify -- npx -y @novalux12/spotify-mcp@latest
# then set SPOTIFY_CLIENT_ID in your shell or MCP env:
export SPOTIFY_CLIENT_ID=your_client_id_here

或者将其添加到项目根目录的 .mcp.json 中 —— 与上面相同的 command/args/env 结构。

面向 AI 代理的命令

任何编码代理（Claude Code、OpenClaw、Cursor、Aider 等）都可以通过一次粘贴完成安装、 构建、认证和注册服务器。给它你的 Client ID，让它运行：

git clone https://github.com/NovaLux12/spotify-mcp-server.git && cd spotify-mcp-server \
  && npm ci && npm run build \
  && SPOTIFY_CLIENT_ID=your_client_id_here npm run auth

然后将你的宿主 MCP 配置指向 <repo>/dist/index.js， 并在其环境中设置 SPOTIFY_CLIENT_ID（结构如下）。代理应最后 调用一次 get_me 工具 —— 它能在 一次往返中验证认证、权限范围和传输。

OpenClaw

添加到 ~/.openclaw/openclaw.json 的 mcp.servers 中：

"spotify": {
  "command": "node",
  "args": ["/path/to/spotify-mcp-server/dist/index.js"],
  "cwd": "/path/to/spotify-mcp-server",
  "env": { "SPOTIFY_CLIENT_ID": "your_client_id_here" }
}

然后重启 OpenClaw 网关，使其重新生成服务器。无头机器？ 在任何有浏览器的机器上使用 SPOTIFY_HEADLESS=1 运行认证步骤 （见上文）—— 无论哪种方式，令牌都会落在 ~/.spotify-mcp/tokens.json 中。

出问题时：安装 doctor 技能

本仓库附带 skills/spotify-mcp-doctor/SKILL.md —— 一个程序化诊断流程，你的代理可以执行它，而不是让你重新阅读 本 README。它按顺序排查真实的故障模式：接线 → 二进制文件 → 应用凭据 → 令牌新鲜度 → 错误分类（Premium vs 开发者模式白名单 vs 市场限制 vs 弃用功能）。安装：

cp -r skills/spotify-mcp-doctor ~/.openclaw/workspace/skills/   # OpenClaw
# or drop it into .claude/skills/ for Claude Code projects

然后只需对你的代理说："Spotify 工具出错了 —— 运行 spotify doctor 技能。"

使用方法

连接后，你可以让 Claude 做这些事情：

• "我热门的 Spotify 曲目有哪些？"

• "创建一个适合学习的轻松 lo-fi 歌曲播放列表"

• "把歌曲 Blinding Lights 添加到我的健身播放列表"

• "我最近听得最多的艺人是谁？"

• "给我做一个深夜开车氛围的播放列表"

故障排除

• 首次调用工具时提示"未认证" —— 运行 npx -y @novalux12/spotify-mcp@latest auth（或从克隆的仓库运行 npm run auth）并完成浏览器流程。令牌存储在 ~/.spotify-mcp/tokens.json 并自动刷新。

• 重定向 URI 不匹配 —— Spotify 应用的重定向 URI 必须精确为 http://127.0.0.1:8888/callback（无尾部斜杠）。保存应用设置后重试。

• 端口 8888 被占用 —— 另一个进程占用了回调端口；停止它，或通过 SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888/callback 选择空闲端口，并在仪表盘中设置匹配的配置。

• 无头 / Docker —— 在 auth 之前设置 SPOTIFY_HEADLESS=1；在提示时粘贴重定向 URL（见上文）。

免责声明

这是一个个人项目，与 Spotify 无关联，也未获得 Spotify 认可。按"原样"提供，不附带任何形式的保证或担保。请负责任地使用，并遵守 Spotify 开发者服务条款。作者不对因使用本软件而产生的任何误用或后果负责。

开发

git clone https://github.com/NovaLux12/spotify-mcp-server.git
cd spotify-mcp-server
npm install
npm run build

将 .env.example 复制为 .env 并填写你的 Client ID，然后：

npm run auth   # authenticate with Spotify
npm run dev    # run from source (no build needed)

需要 Node 22.9+（支持 --env-file-if-exists）。不需要 .env 文件 —— 环境变量来自你的宿主配置或命令行。

测试

npm test   # node:test runner — unit tests for the client and every tool module, plus an MCP protocol smoke test

致谢

• calebWei/SpotifyMCP —— 本项目成长所基于的原始认证流程和播放脚手架。

• varunneal/spotify-mcp —— 作为工具覆盖范围和易用性质量基准的参考实现。

许可证

MIT © Carme99 和 NovaLux12 贡献者。