MCP Claude Spotify

MCP Claude Spotify

特征

• Spotify 身份验证
• 搜索曲目、专辑、艺术家和播放列表
• 播放控制（播放、暂停、下一首、上一首）
• 创建和管理播放列表
• 获得个性化推荐
• 访问用户在不同时间段内最常播放的曲目

演示

要求

• Node.js 16 或更高版本
• Spotify 帐户
• 克劳德桌面
• Spotify API 凭证（客户端 ID 和客户端密钥）

安装

通过 Smithery 安装

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

手动安装

1. 克隆或下载此存储库：

2. 安装依赖项：

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

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

设置 Spotify 凭证

要使用此 MCP，您需要获取 Spotify API 凭证：

1. 前往Spotify 开发者仪表板
2. 使用您的 Spotify 帐户登录
3. 点击“创建应用程序”
4. 填写您的应用信息：
   • 应用程序名称：“MCP Claude Spotify”（或任何你喜欢的名称）
   • 应用程序描述：“Spotify 与 Claude Desktop 的集成”
   • 网站：您可以留空或输入任何 URL
   • 重定向 URI：重要- 添加http://127.0.0.1:8888/callback
5. 接受条款和条件并点击“创建”
6. 在您的应用信息中心，您将看到“客户端 ID”
7. 点击“显示客户端密钥”即可显示您的“客户端密钥”

保存这些凭据，因为您将需要它们进行配置。

运行 MCP 服务器

运行 MCP 服务器有两种方式：

选项 1：手动运行（建议用于首次设置和故障排除）

1. 打开终端或命令提示符
2. 导航到项目目录
3. 直接运行服务器：

使用 Claude Desktop 时，请保持此终端窗口打开。服务器将一直运行，直到您关闭终端。

选项 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 配置。如果该文件不存在，请创建它：

重要提示：替换：

• 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”部分。

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

为了获得更可靠的体验，您可以设置自动启动脚本：

1. 在项目目录中创建一个名为start-spotify-mcp.bat的文件，内容如下：

2. 创建此BAT文件的快捷方式
3. 按Win+R ，输入shell:startup并按 Enter 键
4. 将快捷方式移动到此文件夹，使其随 Windows 启动
5. 在~/Library/LaunchAgents/中创建一个名为com.spotify.mcp.plist的文件，内容如下：

2. 用您的实际值替换路径和凭据
3. 使用以下命令加载代理： launchctl load ~/Library/LaunchAgents/com.spotify.mcp.plist
4. 在~/.config/systemd/user/中创建一个名为spotify-mcp.service的文件（如果目录不存在则创建该目录）：

2. 用您的实际值替换路径和凭据
3. 启用并启动服务：

4. 检查状态：

用法

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 服务器进程。

可用工具

授权 spotify

启动 Spotify 身份验证过程。

搜索 spotify

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

参数：

• query ：搜索文本
• type ：搜索类型（曲目、专辑、艺术家、播放列表）
• limit ：结果数量（1-50）

播放曲目

播放特定曲目。

参数：

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

获取当前播放

获取有关当前播放的信息。

暂停播放

暂停播放。

下一首曲目

跳至下一曲目。

上一曲目

返回上一曲目。

获取用户播放列表

获取用户的播放列表。

创建播放列表

创建新的播放列表。

参数：

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

添加曲目到播放列表

将曲目添加到播放列表。

参数：

• playlistId ：播放列表ID
• trackIds ：轨道 ID 数组

获取建议

根据种子获取建议。

参数：

• seedTracks ：（可选）轨道 ID 数组
• seedArtists ：（可选）艺术家 ID 数组
• seedGenres ：（可选）流派数组
• limit ：（可选）建议数量（1-100）

获取热门曲目

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

参数：

• limit ：（可选）返回的曲目数量（1-50，默认值：20）
• offset ：（可选）要返回的第一个轨道的索引（默认值：0）
• time_range ：（可选）计算亲和力的时间范围：
  • short_term ：大约持续 4 周
  • medium_term ：大约过去 6 个月（默认）
  • long_term ：几年的数据

故障排除

“服务器断开连接”错误

如果您在 Claude Desktop 中看到错误“MCP Spotify：服务器已断开连接”：

1. 验证服务器正在运行：
   • 打开终端并从项目目录手动运行node build/index.js
   • 如果服务器启动成功，则使用 Claude 并保持此终端打开
2. 检查您的配置：
   • 确保claude_desktop_config.json中的绝对路径对于您的系统来说是正确的
   • 仔细检查 Windows 路径是否使用了双反斜杠 ( \\ )
   • 验证您使用的文件系统根目录的完整路径
3. 尝试自动启动选项：
   • 按照“设置自动启动脚本”部分中的说明为您的操作系统设置自动启动脚本
   • 这确保服务器在您需要时始终运行

浏览器不会自动打开

如果认证过程中浏览器没有自动打开，请手动访问： http://127.0.0.1:8888/login 8888/login

身份验证错误

确保您已在 Spotify 开发者仪表板中正确配置了重定向 URI： http://127.0.0.1:8888/callback 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 服务器功能 - 确保工具的正确注册和执行

运行测试

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

运行所有测试：

要运行特定的测试文件：

如果您遇到 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 模块格式编写。

安全说明

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

撤销应用程序访问权限

出于安全原因，您可能希望在以下情况下撤销应用程序对您的 Spotify 帐户的访问权限：

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

要撤销访问权限：

1. 前往您的Spotify 帐户页面
2. 在菜单中导航至“应用程序”
3. 找到“MCP Claude Spotify”（或您为应用选择的名称）
4. 点击“删除访问权限”

这会立即使所有访问和刷新令牌失效。下次使用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. 打开拉取请求

代码风格指南

该项目遵循以下编码标准：

• 使用 TypeScript 进行严格类型检查
• 遵循 ESM 模块格式
• 使用 2 个空格缩进
• 对变量和函数使用驼峰命名法
• 对类和接口使用 PascalCase
• 带有 JSDoc 注释的文档函数
• 保持行长在 100 个字符以内

项目结构

该项目遵循以下结构：

拉取请求流程

1. 确保您的代码遵循样式指南
2. 如果需要，更新文档
3. 添加新功能测试
4. 确保所有测试通过
5. 您的 PR 将由维护人员审核

相关链接

• 模型上下文协议
• Spotify Web API 文档
• 克劳德桌面

执照

该项目根据 Mozilla 公共许可证 2.0 获得许可 - 有关详细信息，请参阅LICENSE文件。