Spotify MCP

SpotifyMCP

Spotify Web API MCP：播放、资料库、播放列表、搜索、播客。与 Spotify 无关联。

提供广泛的 Spotify Web API 工具，另有大多数服务端都没有的额外功能。需要注册才能使用的封装器会有说明，而非隐藏；请参阅需要注册的端点，查看生成的列表。

默认提供的内容，以及如何获取其余内容。 在未设置任何环境变量的情况下启动服务，会注册一组精心挑选的功能——搜索、播放、播放列表、资料库、关注——其规模经过控制，确保在你输入任何内容之前，工具列表不会占据过多上下文窗口。设置 SPOTIFY_MCP_TOOLSETS=all 可注册整个注册表；stats.fm 工具则需通过 SPOTIFY_MCP_STATSFM=1 启用。两项设置都只需在 docs/configuration.md 中添加一行。

在未设置 SPOTIFY_MCP_TOOLSETS 的情况下启动服务，会注册 131 个工具（150,111 字节的架构）——精选的默认功能集（#889）。设置 SPOTIFY_MCP_TOOLSETS=all 可注册全部 562 个工具，以及 17 个固定资源、28 个资源模板和 14 个提示词。工具集和生产环境门控还可以进一步精简已配置的主机；这两个数字均反映了最终处理器执行后，真实生产环境中的 tools/list 结果。

3.0 及更高版本

3.0 发布时，未解决的问题列表清零了——每个史诗、其下的每个问题，以及我们在自查时发现的每一处矛盾，都已解决。大多数积压问题并非会导致崩溃的“错误”，而是此服务报告了未经实际核实的值；这才是真正危险的错误。

由于 Spotify 于 2026 年 2 月删除了相关端点，我们还移除了一些工具——包括艺人关注功能，它完全没有可迁移的目标。

→ 阅读 3.0 路线图

🤖 将以下内容粘贴给你的 Agent

将下面的代码块复制到 Claude Code、Cursor、OpenClaw 或任何编码 Agent 中，即可由它为你设置 SpotifyMCP。

⚠️ 切勿在聊天中粘贴 Spotify 凭据。 Spotify 的开发者条款将 Client ID 视为凭据：§VI.1.1 将“ID、客户端 ID、密钥、密码、安全码或令牌”统称为安全码，§VI.1.3 禁止向任何其他方披露这些信息，§VI.1.4 则规定你有责任为其保密。你在对话中输入的任何内容都会被模型提供商保留、写入 shell 历史记录，并保留在 Agent 的上下文窗口中。此服务只需要 Client ID 这一项凭据，而它属于安全码，并非公开标识符——请像对待密码一样妥善保管。

从 https://github.com/NovaLux12/spotify-mcp-server 设置 Spotify MCP 服务。

1. 引导我在 https://developer.spotify.com/dashboard 创建 Spotify 应用，
   并将重定向 URI 设为 http://127.0.0.1:8888/callback。告诉我在控制面板的
   哪个位置可以找到 Client ID，然后就停下——我会自行复制。
2. 克隆并构建：
   git clone https://github.com/NovaLux12/spotify-mcp-server.git
   cd spotify-mcp-server && npm ci && npm run build
3. 告诉我 MCP 宿主从哪个文件读取服务环境变量。宿主的服务配置始终有效；
   只有通过此仓库的 npm run dev 或 npm start 启动时，才会读取本地 .env，
   因为这两个命令会在 Node >=22.9 上传入 --env-file-if-exists——已发布的
   二进制文件不会读取该文件。打印需要添加的确切代码行。我会自行输入
   Client ID。不要向我要 Client ID，也绝不要复述它。
4. 启动服务并自行运行身份验证命令，然后在浏览器打开后完成登录。此服务
   使用 PKCE，因此没有客户端密钥；除了 Client ID 外，无需获取其他凭据。
5. 使用只读的 spotify_doctor 工具进行验证，并报告其返回的各行内容。

为什么选择它

快速开始

1. 创建 Spotify 应用

打开 Spotify Developer Dashboard → 创建应用 → 添加以下 Redirect URI，内容必须完全一致：

http://127.0.0.1:8888/callback

复制 Client ID。

2. 身份验证

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

此操作会打开浏览器，将令牌保存到 ~/.spotify-mcp/tokens.json，并在之后自动刷新。

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

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

SPOTIFY_HEADLESS=1 SPOTIFY_CLIENT_ID=your_client_id_here npx -y @novalux12/spotify-mcp@latest auth
# prints a URL → open it on any machine → paste the redirect back

3. 添加到 MCP 主机

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

重启主机。聊天输入框中出现锤子图标，即表示已连接。

claude mcp add spotify -- npx -y @novalux12/spotify-mcp@latest
export SPOTIFY_CLIENT_ID=your_client_id_here

"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" }
}

你可以这样提问

• “我这个月最常听的曲目有哪些？”
• “帮我制作一个深夜驾车播放列表”
• “把 Blinding Lights 添加到我的健身播放列表”
• “有哪些播客更新了新单集？”
• “清理我所有播放列表中的重复曲目”
• “我的音乐品味是什么样的？根据它制作一个播放列表”
• “我的 stats.fm 终身流派统计和我这个月听过的流派相符吗？”

配置

全部通过环境变量配置，无需配置文件。只有 SPOTIFY_CLIENT_ID 是必需的。

完整参考：docs/configuration.md

spotify_doctor（CLI + 服务内工具）无需额外设置，即可诊断令牌状态、权限范围缺失、Premium 限制、速率限制冷却时间、请求/配额用量（累计和滚动窗口计数，#904），以及读取缓存压力（保留的条目数、保留的字节数、因响应过大而无法缓存的响应，#894）。

升级到 2.0

2.0 是一个契约版本。一个工具名称已移除，四项内容已调整，另有一项保证已收紧：

0. 已移除 get_show_episodes。 请使用 list_show_episodes（相同的端点、 相同的参数，只是去掉了漂移的别名）。这是唯一更改名称的项目； 其余所有接口名称均保持不变。准确的注册表总数会在本文件顶部 自动生成，因此这里特意不列出数量，以免日后出现差异。

1. 破坏性写入会在无法确认时失败关闭。 现在，任何需要确认的大批量写入 在客户端无法征求确认时都会拒绝执行，而不是未经提示就继续。 archive_played_episodes 的 confirm: true 不再授权删除操作 （该参数仍会被接受，但每条结果都会说明它已被忽略）。对于无头 自动化，请有意设置 SPOTIFY_MCP_CONFIRM=never。

2. 播放列表集合运算的输入采用规范名称。 A/B 对使用 playlist_a/playlist_b；有序列表使用 playlists； playlist_subtract 使用 base_playlist_id 表示基准播放列表。这是 2.0 的契约；此前允许与其并存的旧名称已在 3.0 (#1287) 中撤回。它们不再 出现在任何工具的架构中，仍发送旧名称的调用会在发出任何 Spotify 请求前 被拒绝，并返回 validation 错误，其 reason 为 retired_input，同时 指明实际发送的名称以及应改用的名称。每个工具都只声明了一对别名或一个 别名列表，因此下表是各工具的迁移对照表，而不是一组可同时使用的名称：

   系列	规范名称	该工具以前声明的名称
   A/B 对	playlist_a、playlist_b	a/b，或 playlist_id_a/playlist_id_b，或 playlist_a_id/playlist_b_id——每个工具只使用其中一种
   有序列表	playlists	playlist_ids，或 source_playlist_ids，或 sources——每个工具只使用其中一种
   相减	base_playlist_id + playlists	subtract_playlist_ids，或位置参数形式 playlists: [base, ...sources]——每个工具只使用其中一种

   base_playlist_id 再次成为必填项：位置参数形式已移除，因此调用方 不再有可省略基准播放列表的情况。工具未声明且并非已撤回名称的参数， 会导致 unknown_param 错误——这与 retired_input 表示的情况不同； 后者表示服务端曾将该名称发布到 3.0。

3. 数值上限采用规范名称。 max_results 限制返回的数量； limit 和 scan_cap 限制每个来源的读取量。

4. 拒绝未知参数，并返回带类型的 unknown_param 错误，而不是忽略它们， 因此重命名后的参数会明确报错，而非悄无声息地不起作用。

升级后运行 spotify_doctor：它会在一次调用中报告已注册的接口、 隐藏模块的门控条件，以及已授权的权限范围。

文档

• docs/v3-roadmap.md — 3.0 即将推出的内容，以及贯穿其中的那个 bug
• docs/migration-v3.md — 3.0 中所有废弃的名称及其替代项，包括一个没有替代项的操作
• SPEC.md — 所有工具、资源和提示词
• ARCHITECTURE.md — 构建方式
• docs/configuration.md — 所有环境变量
• docs/cli.md — tools、call、watch、export、init：作为 MCP 客户端的 CLI
• docs/schema-budgets.md — 每个模块的 schema 预算和注册顺序
• docs/statsfm.md — 第二个数据源 stats.fm：设置、工具速查表、注意事项
• docs/cookbook.md — 可直接复制粘贴的 Agent 配方
• docs/non-goals.md — v2 不会做什么、原因，以及它提供的替代方案
• docs/taste.md — 匿名化的品味展示，用于驱动播放列表
• docs/wave2-composites.md — 只读品味组合
• docs/distribution.md — 分发和发行说明
• docs/faq.md — 身份验证、Premium、403、无头模式、令牌
• docs/compliance.md — 品牌标识、署名和出站 User-Agent
• CONTRIBUTING.md — 开发环境设置和约定
• CHANGELOG.md — 发行历史

要求

• 播放控制（播放/暂停/跳过/定位/音量/队列）需要 Premium。免费账户仍可使用搜索、曲库和播放列表。
• Node 22.9+，Spotify 应用须处于开发模式（扩展配额前最多支持 5 位用户）。
• Spotify 将有声书功能限制在美国、英国、加拿大、爱尔兰、新西兰和澳大利亚。
• 部分端点受注册限制——无论作用域或 Premium 状态如何，当前应用注册均会收到 403。已获豁免的注册是否仍会返回 200，尚未验证（#1338）。这是应用注册的属性，而非工具的属性。请参阅受注册限制的端点。

受注册限制的端点

部分 Web API 端点在应用注册级别受到拒绝：对于当前的 Spotify 应用注册，无论授予哪些 OAuth 作用域，也无论账户是否为 Premium，都会返回 403 Forbidden。这是 Spotify 端的限制，并非你的配置错误。

这里没有任何内容是简单地“已移除”。 有三种来源描述了这一类端点，但它们并不一致，因此下表说明的是运行时行为，而非给出定论：

• Spotify 的2026 年 2 月变更日志将一批操作标记为 [REMOVED]。
• 实时 OpenAPI schema仍列出其中大多数相同路径，并标注 deprecated: true，而非将其删除——包括 /artists/{id}/top-tracks 和全部七个 Get Several 批量路径。
• 运行时的实际情况不由这两份文档决定，而取决于你的应用注册获准读取哪些内容。没有相应授权的注册会返回 403/404/410。已获豁免的注册是否仍会返回 200，尚未验证（#1338）：此代码库中没有探测记录能够证明这一点，且唯一曾被引用的探测产物记录的这些路径全部返回 403。

因此，这里的 403 是注册的属性，而非工具的属性。工具不会因为受到限制而隐藏，也没有受限工具是僵尸：每个工具要么读取有文档记录的替代项并返回结果，要么发出调用并用通俗易懂的语言解释 403。权威列表是 src/gating.ts 中的 GATED_FAMILIES 数组——GATED_PATH_PATTERNS 根据它生成，因此分类器与此表不会出现偏差。

Spotify 2026 年 2 月的变更日志将上述全部 8 个系列标记为 [REMOVED] 操作。

请根据权威来源自行确认列表：

grep -n "id: '" src/gating.ts        # the families, with tools and fallback per row

说明：

• 列表中的系列是运行时分类器，并不意味着某个工具一定会调用它。三个系列（browse-new-releases、me-type-contains、playlist-followers-contains）已没有有效调用点——原先使用它们的工具已迁移到替代方案——保留这些模式是为了确保未来的调用者仍受 403 合约保护，而不会在无提示的情况下失去保护。
• GET /me/library/contains 不受限制（在同一次探测中返回了 200），它为 check_playlist_following、restore_library_snapshot 和收据验证背后的已保存状态读取提供支持。上述 contains 系列是变更日志标记为已移除、并由该端点取代的文档中列出的各类型检查。（播放列表重复项清理工具不在此范围内——它们会对 /playlists/{id}/items 进行分页读取。）
• 批量回退（#725）。 当 Get Several 批量端点返回 403 时，fetchSeveral 会通过客户端现有的队列和退避机制，重试逐 ID 调用 GET /<kind>/{id}。逐 ID 路径不属于受限制类别，因此读取仍可成功。响应会携带 degraded: true，并在文本中附带 [degraded: batch endpoint returned 403; … fetched individually] 页脚，同时在 structuredContent 中包含 degraded_reason，这样调用者就能区分逐项往返和正常的批量读取。
• Spotify 列为已移除、但此服务完全没有封装的端点（没有已发布的工具，因此无需说明）：/recommendations、/recommendations/available-genre-seeds、/me/apps、/me/chapters、/artists/{id}/related-artists、/audio-features、/audio-analysis 和 /browse/featured-playlists 读取，以及 /playlists/{id}/tracks 系列（已由 /playlists/{id}/items 取代）。这些端点未列在上表中，因为没有对应工具才是准确的说明——它们没有需要解释的 403。

此服务不提供什么

v2 列出了明确的非目标，因此遇到超出范围的请求时会给出明确答复，而不是含糊其词。以下每项的依据见 SPEC §1，而 docs/non-goals.md 记录了这些说明：每项排除的内容、所依据的来源，以及服务提供的替代方案。

• 音频流、音频分析和离线播放
• Web UI、仪表板或 MCP UI 界面
• 多租户或托管式运行
• 在不同用户之间共享某个用户的凭据
• 歌词
• Spotify Connect SDK 和原生客户端集成
• 语音控制
• 使用 Spotify 数据训练模型，或导出衍生资料
• 第二个第三方上游、广告技术或商业化数据出口
• 绕过 Spotify 自身的控制措施

开发

git clone https://github.com/NovaLux12/spotify-mcp-server.git && cd spotify-mcp-server
npm ci && npm run build
cp .env.example .env  # add your Client ID
npm run auth          # one-time login
npm run dev           # run from source
npm test              # unit + MCP smoke tests

与 Spotify 无关联。请遵守 Spotify Developer Terms。

MIT © Carme99 和 NovaLux12 贡献者 · 感谢 calebWei/SpotifyMCP 和 varunneal/spotify-mcp。