麦克佩-克劳德-斯波蒂菲

Name: 麦克佩-克劳德-斯波蒂菲
Author: imprvhub

作者：imprvhub20 星标更新：2025-11-19

安装使用来源：spider==github.com

项目介绍

技术文档摘要

MCP Claude Spotify

<table style="border-collapse: collapse; width: 100%;"> <tr> <td style="padding: 15px; vertical-align: middle; border: none; text-align: center;"> <a href="https://mseep.ai/app/imprvhub-mcp-claude-spotify"> <img src="https://gips3.baidu.com/it/u=3897459694,3079322203&fm=3081&app=3081&f=PNG?w=502&h=180" alt="MseeP.ai 安全评估徽章" /> </a> </td> <td style="width: 50%; padding: 15px; vertical-align: middle; border: none;">一个允许Claude Desktop通过模型上下文协议（MCP）与Spotify交互的集成。</td> <td style="width: 50%; padding: 0; vertical-align: middle; border: none;"><a href="https://glama.ai/mcp/servers/@imprvhub/mcp-claude-spotify"><img src="https://gips0.baidu.com/it/u=2744055032,2981107179&fm=3081&app=3081&f=PNG?w=760&h=400" alt="Claude Spotify MCP服务器" style="max-width: 100%;" /></a></td> </tr> </table>

特性

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

演示

要求

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

安装

通过Smithery安装

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

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

手动安装

克隆或下载此仓库：

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

安装依赖项：

npm install

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

npm run build

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

设置Spotify凭证

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

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

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

运行MCP服务器

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

方案1：手动运行（建议首次设置和故障排除时使用）

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

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/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”部分即可。

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

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

<details> <summary><b>Windows自动启动说明</b></summary>

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

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

创建该BAT文件的快捷方式
按Win+R，键入shell:startup并按Enter
将快捷方式移动到此文件夹，以便它随Windows启动

</details> <details> <summary><b>macOS自动启动说明</b></summary>

在~/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>

替换路径和凭证为你实际的值
加载代理：launchctl load ~/Library/LaunchAgents/com.spotify.mcp.plist

</details> <details> <summary><b>Linux自动启动说明</b></summary>

在~/.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

替换路径和凭证为你实际的值
启用并启动服务：

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

检查状态：

systemctl --user status spotify-mcp.service

</details>

使用

修改配置后重启Claude Desktop
在Claude中使用auth-spotify命令开始认证过程
浏览器窗口将打开以授权应用程序
使用你的Spotify账户登录并授权应用程序
重要：成功认证后，重启Claude Desktop以正确初始化MCP工具注册和WebSocket会话令牌缓存
重启后，所有Spotify MCP工具都将被正确注册并可供使用

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

可用工具

auth-spotify

启动Spotify认证过程。

search-spotify

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

参数：

query：搜索文本
type：搜索类型（曲目、专辑、艺术家、播放列表）
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：服务器断开连接”的错误：

验证服务器正在运行：
- 打开终端并手动运行node build/index.js从项目目录
- 如果服务器成功启动，请在使用Claude时保持此终端打开
检查你的配置：
- 确保claude_desktop_config.json中的绝对路径对你系统是正确的
- 对于Windows路径，确保你使用了双反斜杠（\\）
- 确认你使用的是从文件系统根开始的完整路径
尝试自动启动选项：
- 根据“设置自动启动脚本”部分的说明设置自动启动脚本
- 这样可以确保服务器始终在你需要时运行

浏览器没有自动打开

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

检查服务器是否运行

要检查服务器是否运行：

Windows：打开任务管理器，转到“详细信息”标签页，并查找“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服务器功能的测试

添加新测试

添加新功能时，请包含相应的测试：

对于新模式，在schemas.test.ts中添加验证测试
对于Spotify API函数，在spotify-api.test.ts中添加测试
对于MCP工具，在server.test.ts中添加测试

所有测试应使用Jest和ESM模块格式以及TypeScript编写。

安全注意事项

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

撤销应用程序访问权限

出于安全原因，当你：

不再使用此集成
怀疑未经授权的访问
在解决认证问题时

可能需要撤销应用程序对你的Spotify账户的访问权限：

前往你的Spotify账户页面
导航到菜单中的“应用”
查找“MCP Claude Spotify”（或你为应用选择的名称）
点击“移除访问权限”

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

贡献

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

开发工作流程

分叉仓库
创建功能分支（git checkout -b feature/amazing-feature）
进行更改
运行测试以确保它们通过（npm test）
提交更改（git commit -m '添加一些精彩的功能'）
推送到分支（git push origin feature/amazing-feature）
打开拉取请求

代码风格指南

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

使用带有严格类型检查的TypeScript
遵循ESM模块格式
使用2个空格进行缩进
使用驼峰命名法（camelCase）用于变量和函数
使用帕斯卡命名法（PascalCase）用于类和接口
使用JSDoc注释文档化函数
保持行长度低于100个字符

项目结构

项目遵循以下结构：

mcp-claude-spotify/
├── src/               # 源代码
├── build/             # 编译后的JavaScript
├── tests/             # 测试文件
├── public/            # 公共资产
└── ...

麦克佩-克劳德-斯波蒂菲

项目介绍

技术文档摘要

MCP Claude Spotify

特性

演示

要求

安装

通过Smithery安装

手动安装

设置Spotify凭证

运行MCP服务器

方案1：手动运行（建议首次设置和故障排除时使用）

方案2：与Claude Desktop自动启动（建议常规使用）

配置

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

使用

可用工具

auth-spotify

search-spotify

play-track

get-current-playback

pause-playback

next-track

previous-track

get-user-playlists

create-playlist

add-tracks-to-playlist

get-recommendations

get-top-tracks

故障排除

“服务器断开连接”错误

浏览器没有自动打开

认证错误

服务器启动错误

工具在Claude中不可见

检查服务器是否运行

测试

运行测试

测试结构

添加新测试

安全注意事项

撤销应用程序访问权限

贡献

开发工作流程

代码风格指南

项目结构

拉