Spotify MCP Server

Spotify MCP 服务

一种媒体控制协议（MCP）服务，可为跨不同设备和应用控制 Spotify 播放提供统一接口。

功能

• 控制 Spotify 播放（播放、暂停、跳过、上一首）
• 调整音量
• 搜索并播放特定曲目、专辑或播放列表
• 获取当前播放信息
• 提供 RESTful API，便于与其他应用集成
• 集成 AI 助手，通过自然语言控制 Spotify
• 提供语音控制界面，通过语音向 Spotify 发出指令

前提条件

• Node.js（v16 或更高版本）
• npm（v8 或更高版本）
• Spotify Premium 账户
• Spotify Developer 账户和已注册的应用

设置

1. 克隆此仓库：

   git clone https://github.com/Jopgood/spotify-mcp-server.git
   cd spotify-mcp-server
   

2. 安装依赖项：

   npm install
   

3. 在根目录中创建 .env 文件，内容如下：

   CLIENT_ID=your_spotify_client_id
   CLIENT_SECRET=your_spotify_client_secret
   REDIRECT_URI=http://localhost:8888/callback
   PORT=8888
   SESSION_SECRET=your_random_session_secret
   AI_WEBHOOK_API_KEY=your_secure_api_key_for_ai_assistant
   BRIDGE_PORT=3001
   VOICE_PORT=3002
   

4. 在 Spotify Developer Dashboard 注册 Spotify 应用，并记下 Client ID 和 Client Secret。

使用方法

1. 启动 MCP 服务：

   npm start
   

2. 打开浏览器并访问 http://localhost:8888，以 Spotify 进行身份验证。

3. 身份验证完成后，即可使用 API 端点控制 Spotify。

API 端点

• GET /api/status - 获取当前播放状态
• POST /api/play - 开始或继续播放
• POST /api/pause - 暂停播放
• POST /api/next - 跳到下一首曲目
• POST /api/previous - 返回上一首曲目
• POST /api/volume - 设置音量（请求体：{ "volume": 50 }）
• POST /api/seek - 跳转到指定位置（请求体：{ "position_ms": 30000 }）
• POST /api/playTrack - 播放指定曲目（请求体：{ "uri": "spotify:track:xxxx" }）

客户端示例

使用 curl

# Play
curl -X POST http://localhost:8888/api/play

# Pause
curl -X POST http://localhost:8888/api/pause

# Next track
curl -X POST http://localhost:8888/api/next

使用 JavaScript（fetch）

// Play a specific track
fetch('http://localhost:8888/api/playTrack', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    uri: 'spotify:track:6rqhFgbbKwnb9MLmUQDhG6'
  })
})
.then(response => response.json())
.then(data => console.log(data));

命令行界面

此项目包含一个命令行界面，可从终端控制 Spotify：

# Run the CLI
node client/spotify-cli.js

# Available commands
status          # Show current playback status
play            # Start/resume playback
pause           # Pause playback
next            # Skip to next track
prev            # Go to previous track
volume 50       # Set volume to 50%
search bohemian # Search for tracks with "bohemian" in the title
play-track spotify:track:xxxx # Play a specific track by URI

AI 助手集成

此 MCP 服务包含一个 AI webhook，允许 Claude 等 AI 助手通过自然语言指令控制 Spotify。

设置集成

1. 在 .env 文件中配置 webhook API 密钥：

   AI_WEBHOOK_API_KEY=your_secure_random_key
   

2. 启动 Claude-Spotify 桥接服务：

   node bridge/claude-spotify-bridge.js
   

3. 桥接服务默认在端口 3001 上运行。你可以在 .env 文件中添加 BRIDGE_PORT=xxxx 来自定义端口。

运行 Claude Spotify 指令

使用提供的客户端脚本执行 Claude 的 Spotify 指令：

node client/claude-spotify-client.js "play bohemian rhapsody"

支持的自然语言指令

AI webhook 支持如下指令：

• “播放 Queen 的《Bohemian Rhapsody》”
• “播放 chill vibes 播放列表”
• “暂停音乐”
• “继续播放”
• “跳到下一首曲目”
• “返回上一首歌曲”
• “将音量设置为 50%”
• “调高音量”
• “调低音量”
• “现在正在播放什么？”

语音控制

如需免手操作，你可以使用语音控制界面，通过语音向 Spotify 发出指令。

设置语音控制

1. 启动语音控制服务：

   node speech/voice-server.js
   

2. 打开浏览器并访问 http://localhost:3002，进入语音控制界面。

3. 确保桥接服务正在运行：

   node bridge/claude-spotify-bridge.js
   

4. 点击麦克风按钮并说出指令，开头加上“Claude”（例如：“Claude，播放一些爵士乐”）。

浏览器兼容性

语音控制界面使用 Web Speech API，并非所有浏览器都支持该 API。为获得最佳效果，请使用：

• Google Chrome（推荐）
• Microsoft Edge
• Safari

Firefox 对 Web Speech API 的支持有限，可能无法正常运行。

自定义语音触发词

你可以将触发词从“Claude”改为任何你喜欢的内容，方法如下：

1. 在语音控制界面中进入 Settings 部分
2. 输入你喜欢的触发词
3. 点击“Save Settings”

你的偏好设置会保存在浏览器中，供后续会话使用。

同时运行所有组件

要运行完整系统（MCP 服务、桥接器和语音界面），可以：

1. 在单独的终端窗口中启动各个组件：

   # Terminal 1: Start MCP server
   npm start
   
   # Terminal 2: Start Claude bridge
   node bridge/claude-spotify-bridge.js
   
   # Terminal 3: Start voice interface
   node speech/voice-server.js
   

2. 或者创建一个简单的启动脚本，一次运行所有组件：

   // Create a file called start-all.js in the root directory with:
   const { spawn } = require('child_process');
   
   const mcp = spawn('npm', ['start'], { stdio: 'inherit' });
   setTimeout(() => {
     const bridge = spawn('node', ['bridge/claude-spotify-bridge.js'], { stdio: 'inherit' });
     const voice = spawn('node', ['speech/voice-server.js'], { stdio: 'inherit' });
   }, 2000);
   
   // Usage: node start-all.js
   

故障排除

• “端口已被占用”错误：

  • 在 .env 文件中更改端口号：PORT、BRIDGE_PORT、VOICE_PORT

• 身份验证问题：

  • 请确保已访问 Web 界面 http://localhost:8888 并使用 Spotify 完成身份验证
  • 检查 .env 中的 Client ID 和 Secret 是否正确

• 语音控制无法使用：

  • 确保使用的是兼容的浏览器（推荐 Chrome）
  • 检查麦克风是否正常工作并已获得必要的权限
  • 确认语音界面设置中的桥接器 URL 与桥接服务器地址一致

• “没有活动设备”错误：

  • 在任意设备上的 Spotify 中开始播放内容，然后重试
  • Spotify 需要有活动设备才能控制播放

开发

要以开发模式运行并启用自动重新加载：

npm run dev

许可证

MIT