MCP Claude Spotify

MCP Claude Spotify

通过 Model Context Protocol (MCP) 让 Claude Desktop 与 Spotify 交互的集成。

已在 0.6.0 中移除 — get-recommendations。 Spotify 于 2024 年 11 月 27 日弃用了 /v1/recommendations， 同时弃用了相关艺人、音频特征、音频分析、精选播放列表和 30 秒预览 URL。 此日期之后创建的应用会收到 403 Forbidden，仍处于开发模式的应用也失去了访问权限，因此该工具几乎对所有人都无法使用。请改用 search-spotify 和 get-top-tracks。 请参阅 Spotify 的公告。

功能

• Spotify 身份验证
• 搜索曲目、专辑、艺人和播放列表
• 播放控制（播放、暂停、下一首、上一首）
• 完整的播放列表管理（创建、更新、删除、重新排序曲目、管理封面图片）
• 读取你的热门曲目和收听记录
• 查看用户在不同时间段内播放次数最多的曲目
• 查看最近播放的曲目

演示

要求

• Node.js 20 或更高版本
• Spotify 账户
• Claude Desktop
• Spotify API 凭据（Client ID 和 Client Secret）

安装

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 MCP Claude Spotify：

npx -y @smithery/cli@latest mcp add imprvhub/mcp-claude-spotify --client claude

手动安装

1. 克隆或下载此仓库：

git clone https://github.com/imprvhub/mcp-claude-spotify
cd claude-spotify-mcp

2. 安装依赖：

npm install

3. 构建项目（如果要修改源代码）：

npm run build

仓库已在 build 目录中包含预构建文件，因此如果不打算修改源代码，可以跳过第 3 步。

设置 Spotify 凭据

要使用此 MCP，你需要获取 Spotify API 凭据：

1. 前往 Spotify Developer Dashboard
2. 使用你的 Spotify 账户登录
3. 点击“Create App”
4. 填写应用信息：
   • 应用名称：“MCP Claude Spotify”（或你喜欢的名称）
   • 应用描述：“Spotify integration for Claude Desktop”
   • 网站：可以留空或填写任意 URL
   • 重定向 URI：重要 - 添加 http://127.0.0.1:8888/callback
5. 接受条款和条件，然后点击“Create”
6. 在应用仪表板中，你会看到“Client ID”
7. 点击“Show Client Secret”以显示“Client Secret”

请保存这些凭据，后续配置时需要用到。

运行 MCP 服务

有两种方式可以运行 MCP 服务：

选项 1：从终端授权一次（首次设置）

Claude Desktop 会启动自己的服务器副本，因此，在终端中保持运行的服务器并不是 Claude 实际连接的服务器。通过终端运行服务器的用途是完成一次授权：设置 SPOTIFY_AUTO_AUTH=true 且没有已保存的令牌时，服务器一启动，就会在浏览器中打开 Spotify 登录页面。

SPOTIFY_CLIENT_ID=your_client_id \
SPOTIFY_CLIENT_SECRET=your_client_secret \
SPOTIFY_AUTO_AUTH=true \
node build/index.js

在浏览器中批准请求。终端显示“Authorization complete”后，按 Ctrl+C 停止进程。令牌会保存到 ~/.spotify-mcp/tokens.json，Claude Desktop 启动的服务器副本会读取该令牌。

你也可以完全跳过这一步，直接让 Claude“authenticate with Spotify”，这会运行 auth-spotify 工具并打开同一个登录页面。

选项 2：随 Claude Desktop 自动启动（推荐日常使用）

Claude Desktop 可以在需要时自动启动 MCP 服务。设置方法如下：

配置

Claude Desktop 的配置文件位于：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

编辑此文件，添加 Spotify MCP 配置。如果文件不存在，请创建该文件：

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["ABSOLUTE_PATH_TO_DIRECTORY/mcp-claude-spotify/build/index.js"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id_here",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

重要：替换以下内容：

• 将 ABSOLUTE_PATH_TO_DIRECTORY 替换为 MCP 的完整绝对路径
  • macOS/Linux 示例：/Users/username/mcp-claude-spotify
  • Windows 示例：C:\\Users\\username\\mcp-claude-spotify
• 将 your_client_id_here 替换为从 Spotify 获取的客户端 ID
• 将 your_client_secret_here 替换为从 Spotify 获取的客户端密钥

如果已配置其他 MCP，只需在 "mcpServers" 对象中添加 "spotify" 部分。

设置自动启动脚本（可选）

如需更可靠的使用体验，可以设置自动启动脚本：

@echo off
cd %~dp0
node build/index.js

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.spotify.mcp</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/node</string>
        <string>ABSOLUTE_PATH_TO_DIRECTORY/mcp-claude-spotify/build/index.js</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardErrorPath</key>
    <string>/tmp/spotify-mcp.err</string>
    <key>StandardOutPath</key>
    <string>/tmp/spotify-mcp.out</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>SPOTIFY_CLIENT_ID</key>
        <string>your_client_id_here</string>
        <key>SPOTIFY_CLIENT_SECRET</key>
        <string>your_client_secret_here</string>
    </dict>
</dict>
</plist>

[Unit]
Description=Spotify MCP Server for Claude Desktop
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/node ABSOLUTE_PATH_TO_DIRECTORY/mcp-claude-spotify/build/index.js
Restart=on-failure
Environment="SPOTIFY_CLIENT_ID=your_client_id_here"
Environment="SPOTIFY_CLIENT_SECRET=your_client_secret_here"

[Install]
WantedBy=default.target

systemctl --user enable spotify-mcp.service
systemctl --user start spotify-mcp.service

systemctl --user status spotify-mcp.service

开发

npm install
npm run build
npm test

使用方法

1. 修改配置后，重启 Claude Desktop
2. 在 Claude 中使用 auth-spotify 命令启动身份验证流程
3. 浏览器窗口将打开，供你授权此应用
4. 使用 Spotify 账号登录并授权此应用
5. 重要：成功完成身份验证后，重启 Claude Desktop，以正确初始化 MCP 的工具注册表和 WebSocket 会话令牌缓存
6. 重启后，所有 Spotify MCP 工具都将正确注册并可供使用

MCP 服务作为由 Claude Desktop 管理的子进程运行。Claude 运行时，会根据 claude_desktop_config.json 中的配置自动启动并管理 Node.js 服务进程。

安全说明

• 授权受到 CSRF 保护。 登录 URL 会携带一个随机的 state 值，回调会在交换授权码前验证该值。0.6.0 之前的版本不会发送 state，因此浏览器中打开的任何页面都可能访问环回回调，并绑定到另一个 Spotify 账户。
• 令牌文件仅所有者可访问。 ~/.spotify-mcp/tokens.json 保存长期有效的刷新令牌，现在会以 600 权限写入 700 权限的目录。此前该文件使用默认权限创建，导致机器上的每个账户都能读取。
• 不会通过结束进程来释放端口。 如果端口 8888 被占用，服务会报告该情况并停止。早期版本会运行 lsof -i:8888 -t | xargs kill -9（Windows 上则运行对应的 taskkill 命令），以 SIGKILL 结束任何占用这个极常用开发端口的无关进程。
• 工具参数中的 ID 会经过验证。 曲目、播放列表和设备 ID 会用于 API 路径和查询字符串，因此只接受普通 Spotify ID；其他内容会在构建请求前被拒绝。
• 回调仅监听环回地址（127.0.0.1）。此前的 express 监听器会绑定所有网络接口，因此同一网络上的任何人都能访问 /login 和 /callback。容器可通过 AUTH_BIND_HOST=0.0.0.0 扩大监听范围。
• 授权完成后，回调服务会关闭，而不会在整个会话期间持续绑定。

可用工具

身份验证

auth-spotify

启动 Spotify 身份验证流程。

搜索

search-spotify

搜索曲目、专辑、艺人或播放列表。

参数：

• query：搜索文本
• type：搜索类型（track、album、artist、playlist）
• limit：结果数量（1-10，默认值：5）

播放控制

get-current-playback

获取当前播放状态的信息。

play-track

在活跃设备上播放指定曲目。

参数：

• trackId：Spotify 曲目 ID
• deviceId：（可选）用于播放的 Spotify 设备 ID

pause-playback

暂停当前播放。

next-track

跳到下一首曲目。

previous-track

返回上一首曲目。

播放列表管理

get-user-playlists

获取用户的播放列表。

参数：

• limit：（可选）要返回的播放列表数量（1-50，默认值：20）
• offset：（可选）要返回的第一个播放列表的索引（默认值：0）

create-playlist

为当前用户创建新的播放列表。

参数：

• name：播放列表名称
• description：（可选）描述
• public：（可选）是否公开

update-playlist

更新播放列表的名称、描述、公开/私密状态或协作设置。

参数：

• playlistId：播放列表的 Spotify ID
• name：（可选）播放列表的新名称
• description：（可选）新的描述
• public：（可选）播放列表是否应公开
• collaborative：（可选）播放列表是否应允许协作（必须先将 public 设为 false）

delete-playlist

取消关注（从你的资料库中移除）播放列表。该播放列表仍存在于 Spotify 上，但不再位于你的资料库中。

参数：

• playlistId：播放列表的 Spotify ID

get-playlist-tracks

获取播放列表中的曲目，支持分页。

参数：

• playlistId：播放列表的 Spotify ID
• limit：（可选）要返回的曲目数量（1-50，默认值：20）
• offset：（可选）要返回的第一首曲目的索引（默认值：0）

add-tracks-to-playlist

将曲目添加到播放列表。

参数：

• playlistId：播放列表 ID
• trackIds：曲目 ID 数组

remove-tracks-from-playlist

从播放列表中移除曲目。

参数：

• playlistId：播放列表的 Spotify ID
• trackIds：要移除的 Spotify 曲目 ID 数组

reorder-playlist-tracks

通过将一段曲目移动到新位置，重新排序播放列表中的曲目。

参数：

• playlistId：播放列表的 Spotify ID
• rangeStart：要移动的第一首曲目的位置
• insertBefore：插入曲目的位置
• rangeLength：（可选）要移动的曲目数量（默认值：1）

get-playlist-cover

获取播放列表的封面图片。

参数：

• playlistId：播放列表的 Spotify ID

upload-playlist-cover

为播放列表上传自定义封面图片（经 Base64 编码的 JPEG，最大 256KB）。

参数：

• playlistId：播放列表的 Spotify ID
• imageBase64：经 Base64 编码的 JPEG 图片

发现与历史记录

get-top-tracks

获取用户在指定时间范围内播放次数最多的曲目。

参数：

• limit：（可选）要返回的曲目数量（1-50，默认值：20）
• offset：（可选）要返回的第一首曲目的索引（默认值：0）
• time_range：（可选）用于计算偏好的时间范围：
  • short_term：大约最近 4 周
  • medium_term：大约最近 6 个月（默认值）
  • long_term：数年的数据

get-recently-played

获取用户最近播放的曲目。

参数：

• limit：（可选）要返回的曲目数量上限（1-50，默认值：20）
• before：（可选）以毫秒为单位的 Unix 时间戳。返回此时间之前播放的曲目
• after：（可选）以毫秒为单位的 Unix 时间戳。返回此时间之后播放的曲目

故障排除

“Server disconnected”错误

如果你在 Claude Desktop 中看到错误“ MCP Spotify: Server disconnected”：

1. 确认服务正在运行：

   • 打开终端，在项目目录中手动运行 node build/index.js
   • 如果服务成功启动，请保持此终端打开并使用 Claude

2. 检查配置：

   • 确认 claude_desktop_config.json 中的绝对路径适用于你的系统
   • 再次确认 Windows 路径使用了双反斜杠（\\）
   • 确认使用的是从文件系统根目录开始的完整路径

3. 尝试自动启动选项：

   • 按照“设置自动启动脚本”部分的说明，为你的操作系统设置自动启动脚本
   • 这样可以确保你需要时服务始终处于运行状态

浏览器未自动打开

如果身份验证期间浏览器没有自动打开，请手动访问： http://127.0.0.1:8888/login

身份验证错误

请确保已在 Spotify Developer 控制面板中正确配置重定向 URI： http://127.0.0.1:8888/callback

服务启动错误

请确认：

• 已在 claude_desktop_config.json 或启动脚本中正确配置环境变量
• 已安装 Node.js，且版本兼容（v16+）
• 所需端口（8888）可用，且未被防火墙阻止
• 你有权限在指定位置运行脚本

工具未显示在 Claude 中

如果身份验证后 Spotify 工具未显示在 Claude 中：

• 确保成功完成身份验证后重启了 Claude Desktop
• 检查 Claude Desktop 日志中是否有 MCP 通信错误
• 确认 MCP 服务进程正在运行（手动运行以进行确认）
• 确认 MCP 服务已在 Claude Desktop MCP 注册表中正确注册

检查服务是否正在运行

要检查服务是否正在运行：

• Windows：打开任务管理器，进入“详细信息”选项卡，查找“node.exe”
• macOS/Linux：打开终端并运行 ps aux | grep node

如果服务未运行，请手动启动，或使用自动启动方式。

测试

本项目包含自动化测试，以确保代码质量和功能正常。测试套件使用支持 TypeScript 的 Jest，涵盖：

• Zod 架构验证 - 验证所有输入架构是否能正确校验数据
• Spotify API 交互 - 测试 API 请求处理和错误处理
• MCP 服务功能 - 确保工具能够正确注册和执行

运行测试

首先，确保已安装所有开发依赖项：

npm install

运行所有测试：

npm test

运行指定的测试文件：

npm test -- --testMatch="**/tests/schemas.test.ts"

如果遇到 ESM 模块问题，请确保使用 Node.js v16 或更高版本，并且 NODE_OPTIONS 环境变量包含 package.json 中配置的 --experimental-vm-modules 标志。

测试结构

• tests/schemas.test.ts：输入验证架构测试
• tests/spotify-api.test.ts：Spotify API 交互测试
• tests/server.test.ts：MCP 服务功能测试

添加新测试

添加新功能时，请务必编写相应的测试：

1. 对于新的架构，在 schemas.test.ts 中添加验证测试
2. 对于 Spotify API 函数，在 spotify-api.test.ts 中添加测试
3. 对于 MCP 工具，在 server.test.ts 中添加测试

所有测试都应使用 Jest 编写，并采用 TypeScript 的 ESM 模块格式。

安全说明

• 切勿分享你的 Client ID 和 Client Secret
• 访问令牌现在存储在用户的主目录 ~/.spotify-mcp/tokens.json 中，以便在不同会话和多个实例之间持久保存
• 不会在磁盘上存储任何用户数据

撤销应用访问权限

出于安全考虑，在以下情况下，你可能需要撤销应用对 Spotify 帐户的访问权限：

• 不再使用此集成
• 怀疑存在未经授权的访问
• 正在排查身份验证问题

撤销访问权限：

1. 前往你的 Spotify 帐户页面
2. 在菜单中进入“Apps”
3. 找到“MCP Claude Spotify”（或你为应用选择的名称）
4. 点击“REMOVE ACCESS”

这会立即使所有访问令牌和刷新令牌失效。下次使用 auth-spotify 命令时，你需要重新授权该应用。

贡献

欢迎贡献！请遵循以下指南：

开发工作流

1. 复刻此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 进行更改
4. 运行测试，确保测试通过（npm test）
5. 提交更改（git commit -m 'Add some amazing feature'）
6. 推送到分支（git push origin feature/amazing-feature）
7. 发起 Pull Request

代码风格指南

本项目遵循以下编码规范：

• 使用 TypeScript，并启用严格类型检查
• 遵循 ESM 模块格式
• 使用 2 个空格缩进
• 变量和函数使用 camelCase 命名
• 类和接口使用 PascalCase 命名
• 使用 JSDoc 注释编写函数文档
• 将行长度控制在 100 个字符以内

项目结构

本项目采用以下结构：

mcp-claude-spotify/
├── src/               # Source code
├── build/             # Compiled JavaScript
├── tests/             # Test files
├── public/            # Public assets
└── ...

Pull Request 流程

1. 确保代码符合风格指南
2. 根据需要更新文档
3. 为新功能添加测试
4. 确保所有测试均通过
5. 维护者将审核你的 PR

相关链接

• Model Context Protocol
• Spotify Web API Documentation
• Claude Desktop
• MCP Series

许可证

本项目采用 Mozilla Public License 2.0 许可，详情请参阅 LICENSE 文件。