Spotify语音控制服务

🎵 Spotify MCP 服务器

一个模型上下文协议（MCP）服务器，它将Spotify与Claude集成，使得用户能够通过对话式人工智能直接实现语音控制音乐播放、播放列表管理以及个性化音乐推荐。

✨ 特点/功能

🎵 播放控制

• 获取当前播放曲目的完整信息
• 通过名称或ID播放特定曲目
• 暂停/继续播放
• 跳到下一首/上一首曲目
• 调整音量大小
• 切换洗牌模式

❤️ 图书馆管理

• 点赞/取消点赞歌曲
• 将曲目添加到喜欢的歌曲中
• 从喜欢的歌曲中移除曲目

📝 播放列表操作

• 创建新的播放列表
• 向现有播放列表添加曲目
• 搜索并发现音乐

🔍 发现与搜索

• 搜索歌曲、艺术家、专辑和播放列表
• 获取个性化推荐
• 查看热门曲目和艺术家（可自定义时间范围）

📊 分析

• 查看你播放次数最多的曲目
• 查看你的顶级艺术家
• 分析不同时间段的听力习惯

🚀 前提条件

• Node.js 版本 18 或更高版本
• 克劳德桌面版
• Spotify高级会员账户（播放控制所需）
• Spotify开发者账户

📦 安装

1. 创建Spotify开发者应用

1. 首选 Spotify 开发者仪表板
2. 使用您的Spotify帐户登录
3. 点击 “创建应用”
4. 填写：
   • 应用名称： Claude MCP Integration
   • 应用描述: MCP server for Claude AI
   • 重定向URI： http://localhost:3000/callback ⚠️ 关键的；严重的
5. 保存并记下你的 客户端ID 和 客户端密钥

2. 克隆并设置

# Clone the repository
git clone https://github.com/MadhurToshniwal/Spotify-MCP-Server.git
cd Spotify-MCP-Server

# Install dependencies
npm install

# Build the project
npm run build

3. 配置环境变量

创建一个 .env 项目根目录中的文件：

SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here
SPOTIFY_REFRESH_TOKEN=will_get_this_next

4. 授权您的Spotify账户

运行OAuth辅助脚本：

npm run auth

这将会：

1. 在3000端口启动本地服务器
2. 打开您的浏览器，进入Spotify的授权页面
3. 授权后，请展示您的 刷新令牌
4. 复制刷新令牌并将其添加到您的 .env 文件

5. 配置Claude桌面版

编辑您的Claude桌面配置文件：

Windows： %APPDATA%\Claude\claude_desktop_config.json
macOS（发音为“Mac OS”，其中“Mac”是“Macintosh”的简称，指苹果公司的电脑系统）: ~/Library/Application Support/Claude/claude_desktop_config.json

添加此配置：

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": [
        "/absolute/path/to/spotify-mcp-server/dist/index.js"
      ],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

对Windows用户而言很重要在路径中使用双反斜杠：

"args": ["C:\\Users\\YourName\\Desktop\\spotify-mcp-server\\dist\\index.js"]

6. 重启Claude桌面版

要使更改生效，请完全退出并重新启动 Claude 桌面版。

🎮 使用示例

一旦配置完成，您就可以向Claude询问：

播放控制

• “我在听什么歌？”
• “暂停音乐”
• “播放下一首歌”
• “将音量设置为70%”
• “开启随机播放”

搜索与发现

• “搜索The Weeknd的歌曲”
• “找一些爵士乐播放列表”
• “搜索专辑《Abbey Road》”

图书馆管理

• “将这首歌添加到我的喜欢歌曲中”
• “与这条路线不同”
• “创建一个名为‘健身混音’的播放列表”
• “将这3首歌添加到我的播放列表”

分析（或分析学）

• “我这个月的十大歌曲是什么？”
• “给我显示我播放次数最多的艺术家”
• “我最近都在听些什么？”

高级

• “搜索‘波西米亚狂想曲’并播放”
• “创建一个名为‘学习音乐’的播放列表，并添加5首舒缓的歌曲”
• “查找电子音乐播放列表并播放最受欢迎的一个”

🛠️ 可用工具

🔒 安全注意事项

• 永远不要让你的 .env 文件提交到版本控制系统
• 确保您的客户端密钥安全
• 刷新令牌有效期长，请安全存储
• 服务器使用OAuth 2.0并自动刷新令牌

📊 API 限制

Spotify Web API 的速率限制：

• Web API调用受到Spotify的速率限制
• 大多数终端点每秒允许处理多个请求
• 服务器会自动处理令牌刷新

🐛 故障排除

“未找到活动设备”

解决方案在您的设备上打开Spotify并播放任意歌曲以激活设备。

“无效的刷新令牌”

解决方案跑 npm run auth 再次获取一个新的刷新令牌。

工具未在Claude中显示

解决方案:

1. 验证路径中的（内容） claude_desktop_config.json 是正确的
2. 确保所有环境变量都已设置
3. 完全重启Claude桌面版

“需要高级权限”错误

解决方案某些功能（播放控制）需要Spotify高级会员。

📁 项目结构

spotify-mcp-server/
├── src/
│   ├── index.ts                # Main MCP server
│   └── get-refresh-token.ts    # OAuth helper script
├── dist/                       # Compiled JavaScript
├── .env                        # Environment variables (not in repo)
├── package.json
├── tsconfig.json
└── README.md

🚀 开发

# Build the project
npm run build

# Run the OAuth helper
npm run auth

# Run in development
npm start

🧪 所用技术

• TypeScript类型安全的开发
• **模型上下文协议（MCP）**标准克劳德集成
• Spotify Web API音乐流媒体服务API
• OAuth 2.0安全认证协议
• Express.js用于OAuth流程的Web服务器
• **Axios（注：Axios是一个用于浏览器和Node.js的基于promise的HTTP客户端）**API请求的HTTP客户端

📜 许可证

麻省理工学院（MIT）

👤 作者

马杜尔·托什尼瓦尔

📧 电子邮件：madhurtoshniwal03@gmail.com

🙏 致谢

• Spotify的全面Web API
• 针对模型上下文协议的Anthropic（注：此处“Anthropic”可能指的是一个特定的公司、框架或协议名称，根据上下文具体含义翻译，若直接指代公司则译为“人智主义公司”，但在此处为保持技术或协议名称的通用性，未做具体展开）
• 用于AI集成的Claude桌面版

为校园招聘面试而构建，展示API集成、OAuth实现以及现代开发实践。

🎓 学习成果

这个项目展示了：

• OAuth 2.0认证流程的实现
• RESTful API集成与错误处理
• 安全凭证管理
• 实时数据同步
• 使用TypeScript进行类型安全开发
• MCP协议实现
• 异步编程模式