Vuples Spotify MCP 服务器

一个模型上下文协议（MCP）服务器，使像 Claude 这样的 AI 助手能够与 Spotify 交互，允许它们搜索和播放曲目。

功能

• 按艺术家、标题或任何查询搜索曲目
• 直接在您的活动 Spotify 设备上播放曲目
• 获取当前播放曲目的信息
• 查找可用的 Spotify 播放设备
• 结合搜索和播放功能
• 列出用户的 Spotify 播放列表
• 查看播放列表中的曲目
• 播放播放列表（可选随机播放模式）
• 按名称查找并播放播放列表

要求

• Node.js (v16+)
• Spotify 开发者账户
• Spotify Premium 账户（用于播放功能）
• 一个兼容 MCP 的客户端（例如 Claude Desktop）

安装

1. 克隆此仓库：
   bash
   git clone https://github.com/yourusername/spotify-mcp.git
   cd spotify-mcp

2. 安装依赖项：
   bash
   npm install

3. 创建一个包含您的 Spotify API 凭证的 .env 文件：

   SPOTIFY_CLIENT_ID=your_client_id
   SPOTIFY_CLIENT_SECRET=your_client_secret
   SPOTIFY_REDIRECT_URI=http://localhost:8888

   可选：用于播放控制

   SPOTIFY_REFRESH_TOKEN=your_refresh_token

   您可以从 Spotify 开发者仪表板 获取您的 Client ID 和 Secret。

4. 生成刷新令牌（播放控制必需）：

   有两种方法可以获取刷新令牌：

   选项 1：使用内置脚本
   bash
   npm run get-token

   这将启动一个本地服务器并在终端中提供说明。

   选项 2：使用简单脚本（如果选项 1 不起作用）
   bash
   node src/simple-auth.js

   这将为您提供一个在浏览器中打开的 URL。授权后，您将被重定向到另一个 URL。将该 URL 复制回终端，它将显示一个 curl 命令以获取刷新令牌。

   所需权限范围（已在脚本中包含）：

   • user-read-playback-state
   • user-modify-playback-state
   • user-read-currently-playing
   • playlist-read-private
   • playlist-read-collaborative

5. 将刷新令牌添加到您的 .env 文件中：

   SPOTIFY_REFRESH_TOKEN=your_refresh_token

6. 构建项目：
   bash
   npm run build

使用 Claude Desktop

1. 首先，确保 Spotify 在您的设备上打开并正在播放

2. 将此服务器添加到您的 Claude Desktop 配置中：

   编辑您的 claude_desktop_config.json 文件（通常在 macOS 上位于 ~/Library/Application Support/Claude/ 或 Windows 上位于 %APPDATA%\Claude\）：

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

   确保将 /absolute/path/to/vulpes-spotify-mcp 替换为您的项目实际路径。

3. 重启 Claude Desktop

4. 当您点击 Claude Desktop 中的锤子图标时，现在应该可以看到可用的 Spotify 工具

可用工具

• spotify-search: 按查询搜索曲目
• spotify-play: 按 ID 或 URI 播放特定曲目
• spotify-currently-playing: 获取当前播放曲目的信息
• spotify-devices: 列出可用的 Spotify 播放设备
• spotify-search-and-play: 搜索曲目并自动播放最匹配的结果
• spotify-playlists: 获取用户的 Spotify 播放列表
• spotify-playlist-tracks: 从特定播放列表中获取曲目
• spotify-play-playlist: 播放特定播放列表（可选随机播放）
• spotify-find-playlist: 按名称查找并播放播放列表（推荐用于 AI 使用）

故障排除- "未找到活动设备": 确保 Spotify 在至少一个设备上打开并正在播放

• "缺少权限": 您的刷新令牌可能没有所需的范围
• "非高级账户": 播放控制需要 Spotify 高级账户
• "刷新令牌问题": 如果您的令牌过期，请按照安装部分中的步骤生成新的令牌

重要提示

1. 在使用播放控制之前，始终确保 Spotify 在至少一个设备上打开
2. 您的 .env 文件和 Claude Desktop 配置中的刷新令牌必须匹配
3. 在更改配置后，重启 Claude Desktop

许可证

MIT