MCP Claude Spotify

MCP克劳德Spotify

  ](https://smithery.ai/server/@imprvhub/mcp-claude-spotify)

An integration that allows Claude Desktop to interact with Spotify using the Model Context Protocol (MCP).

特性

• Spotify身份验证
• 搜索曲目、专辑、艺术家和播放列表
• 播放控制（播放、暂停、下一个、上一个）
• 完整的播放列表管理（创建、更新、删除、重新排序曲目、管理封面图像）
• 获取个性化推荐
• 访问用户在不同时间段播放的热门曲目
• 查看最近播放的曲目

演示

需求

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

安装

通过Smithery安装

通过以下方式自动安装MCP Claude Spotify for Claude Desktop 史密瑟里:

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

手动安装

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集成” - 网站：您可以留空或输入任何网址 - 重定向URI: 重要 -添加 http://127.0.0.1:8888/callback

1. 接受条款和条件，然后单击“创建”
2. 在您的应用仪表板中，您将看到“客户端ID”
3. 点击“显示客户端密码”以显示您的“客户端密码”

将这些凭据保存为配置所需。

运行MCP服务器

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

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

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

node build/index.js

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

选项2：使用Claude Desktop自动启动（建议常规使用）

克劳德桌面可以在需要时自动启动MCP服务器。要设置此项，请执行以下操作：

配置

Claude Desktop配置文件位于：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %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”部分即可。

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

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

Windows auto-start instructions

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

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

1. 创建此BAT文件的快捷方式
2. 按 Win+R，类型 shell:startup 然后按Enter键
3. 移动此文件夹的快捷方式，使其从Windows开始

macOS auto-start instructions

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

    Label
    com.spotify.mcp
    ProgramArguments
    
        /usr/local/bin/node
        ABSOLUTE_PATH_TO_DIRECTORY/mcp-claude-spotify/build/index.js
    
    RunAtLoad
    
    KeepAlive
    
    StandardErrorPath
    /tmp/spotify-mcp.err
    StandardOutPath
    /tmp/spotify-mcp.out
    EnvironmentVariables
    
        SPOTIFY_CLIENT_ID
        your_client_id_here
        SPOTIFY_CLIENT_SECRET
        your_client_secret_here
    

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

Linux auto-start instructions

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

[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. 在克劳德，使用 auth-spotify 启动身份验证过程的命令
3. 浏览器窗口将打开，供您授权应用程序
4. 使用您的Spotify帐户登录并授权该应用程序
5. 重要：身份验证成功后，重新启动Claude Desktop以正确初始化MCP的工具注册表和WebSocket会话令牌缓存
6. 重新启动后，所有Spotify MCP工具都将正确注册并可供使用

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

可用工具

认证

身份验证

启动Spotify身份验证过程。

搜索

搜索spotify

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

参数：

• query：搜索文本
• type：搜索类型（曲目、专辑、艺术家、播放列表）
• limit：结果数（1-10，默认值：5）

回放控制

获取当前播放

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

播放曲目

在活动设备上播放特定曲目。

参数：

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

暂停播放

暂停当前播放。

下一轨道

跳到下一条轨道。

上一轨道

返回上一轨道。

播放列表管理

获取用户播放列表

获取用户播放列表的列表。

参数：

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

创建播放列表

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

参数：

• name：播放列表名称
• description：（可选）描述
• public：（可选）无论是公共还是私人

更新播放列表

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

参数：

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

删除播放列表

从库中取消关注（删除）播放列表。该播放列表仍然存在于Spotify上，但已不在您的库中。

参数：

• playlistId：播放列表的Spotify ID

获取播放列表曲目

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

参数：

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

将曲目添加到播放列表

将曲目添加到播放列表中。

参数：

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

从播放列表中删除曲目

从播放列表中删除曲目。

参数：

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

重新排序播放列表曲目

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

参数：

• playlistId：播放列表的Spotify ID
• rangeStart：要移动的第一个轨道的位置
• insertBefore：轨道应插入的位置
• rangeLength：（可选）要移动的轨迹数（默认值：1）

获取播放列表封面

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

参数：

• playlistId：播放列表的Spotify ID

上传播放列表封面

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

参数：

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

发现与历史

获取推荐

获取基于种子曲目、艺术家或流派的曲目推荐。

参数：

• seedTracks：（可选）Spotify曲目ID数组
• seedArtists：（可选）Spotify艺术家ID数组
• seedGenres：（可选）流派名称数组
• limit：（可选）建议数（1-100，默认值：20）

获取热门曲目

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

参数：

• limit：（可选）要返回的曲目数（1-50，默认值：20）
• offset：（可选）要返回的第一个曲目的索引（默认值：0）
• time_range：（可选）计算亲和力的时间范围：

- short_term：大约过去4周 - medium_term：大约过去6个月（默认） - long_term：几年的数据

最近玩过

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

参数：

• limit：（可选）要返回的最大曲目数（1-50，默认值：20）
• before：（可选）Unix时间戳（毫秒）。返回在此时间之前播放的曲目
• after：（可选）Unix时间戳（毫秒）。返回在此时间之后播放的曲目

故障排除

“服务器已断开连接”错误

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

1. 验证服务器是否正在运行:

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

1. 检查您的配置:

- 确保绝对路径 claude_desktop_config.json 适用于您的系统 - 仔细检查你是否使用了双睫毛(\\)对于Windows路径 - 验证您使用的是从文件系统根目录开始的完整路径

1. 尝试自动启动选项:

- 按照“设置自动启动脚本”一节中的说明为您的操作系统设置自动启动剧本 - 这确保了服务器在您需要时始终运行

浏览器不会自动打开

如果浏览器在身份验证过程中没有自动打开，请手动访问： 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中

如果验证后Spotify工具未出现在Claude中：

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

检查服务器是否正在运行

要检查服务器是否正在运行，请执行以下操作：

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

如果您没有看到服务器正在运行，请手动启动或使用自动启动方法。

测试

该项目包括自动化测试，以确保代码质量和功能。测试套件使用Jest和TypeScript支持，包括：

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

运行测试

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

npm install

要运行所有测试，请执行以下操作：

npm test

要运行特定的测试文件，请执行以下操作：

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

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

测试结构

• 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个空格进行缩进
• 将camelCase用于变量和函数
• 对类和接口使用PascalCase
• 带有JSDoc注释的文档功能
• 保持行长度不超过100个字符

项目结构

该项目遵循以下结构：

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

拉取请求流程

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

相关链接

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

许可证

此项目根据Mozilla公共许可证2.0获得许可-请参阅 许可证 文件以获取详细信息。