MCP Claude Spotify

功能

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

演示

要求

• Node.js 16 或更高版本
• Spotify账户
• Claude Desktop
• Spotify API凭证（客户端ID和客户端密钥）

安装

1. 克隆或下载此仓库：

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

1. 安装依赖项：

npm install

1. 构建项目（如果您打算修改源代码）：

npm run build

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

设置Spotify凭证

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

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

保存这些凭证，因为配置时会需要用到它们。

运行MCP服务器

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

选项1：手动运行（首次设置和故障排除推荐）

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

node build/index.js

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

{
  "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/用户名/mcp-claude-spotify
  • Windows 示例：C:\\Users\\用户名\\mcp-claude-spotify
• your_client_id_here 替换为你从 Spotify 获取的 Client ID
• your_client_secret_here 替换为你从 Spotify 获取的 Client Secret

如果你已经配置了其他 MCP，则只需在 "mcpServers" 对象中添加 "spotify" 部分即可。

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

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

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

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

1. 创建指向此 BAT 文件的快捷方式
2. 按 Win+R，输入 shell:startup 并按 Enter 键
3. 将快捷方式移动到此文件夹，以便随 Windows 启动

1. 在 ~/Library/LaunchAgents/ 中创建一个名为 com.spotify.mcp.plist 的文件，内容如下：

<?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>

1. 将路径和凭据替换为你的实际值
2. 使用以下命令加载代理：launchctl load ~/Library/LaunchAgents/com.spotify.mcp.plist

1. 在 ~/.config/systemd/user/ 中创建一个名为 spotify-mcp.service 的文件（如果目录不存在则创建）：

[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

1. 将路径和凭据替换为你的实际值
2. 启用并启动服务：

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

1. 使用以下命令检查状态：

systemctl --user status spotify-mcp.service

使用方法

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

可用工具

auth-spotify

启动 Spotify 认证过程。

search-spotify

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

参数：

• query：搜索文本
• type：搜索类型（track, album, artist, playlist）
• limit：结果数量（1-50）

play-track

播放特定曲目。

参数：

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

get-current-playback

获取当前播放的信息。

pause-playback

暂停播放。

next-track

跳到下一首曲目。

previous-track

返回上一首曲目。

get-user-playlists

获取用户的播放列表。

create-playlist

创建一个新的播放列表。

参数:

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

add-tracks-to-playlist

向播放列表中添加曲目。

参数:

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

get-recommendations

基于种子获取推荐。

参数:

• seedTracks: （可选）曲目ID数组
• seedArtists: （可选）艺术家ID数组
• seedGenres: （可选）流派数组
• limit: （可选）推荐数量（1-100）

get-top-tracks

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

参数:

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

故障排除

"服务器断开连接" 错误

如果您在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开发者控制台中正确配置了重定向URI:
http://127.0.0.1:8888/callback

服务器启动错误

请验证以下几点：

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

Claude中未出现工具

如果认证后Claude中未显示Spotify工具：

• 确保在成功认证后重启了 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 和 ESM 模块格式与 TypeScript 编写。

安全注意事项

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

撤销应用程序访问权限

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

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

要撤销访问权限：

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

这将立即使所有访问令牌和刷新令牌失效。下次使用 auth-spotify 命令时，您需要再次授权该应用程序。

贡献

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

开发工作流程

1. Fork 仓库
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 将由维护者审核

相关链接

• 模型上下文协议
• Spotify Web API 文档
• Claude 桌面版

许可证

本项目根据 Mozilla Public License 2.0 许可发布 - 详情请参阅 LICENSE 文件。