Vulpes Spotify MCP Server

Vuples Spotify MCP 服务器

模型上下文协议 (MCP) 服务器使 Claude 等 AI 助手能够与 Spotify 进行交互，从而允许他们搜索和播放曲目。

特征

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

要求

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

安装

1. 克隆此存储库：
   git clone https://github.com/yourusername/spotify-mcp.git cd spotify-mcp
2. 安装依赖项：
   npm install
3. 使用您的 Spotify API 凭证创建一个.env文件：
   SPOTIFY_CLIENT_ID=your_client_id SPOTIFY_CLIENT_SECRET=your_client_secret SPOTIFY_REDIRECT_URI=http://localhost:8888 # Optional: For playback control SPOTIFY_REFRESH_TOKEN=your_refresh_token
   您可以从Spotify 开发者仪表板获取您的客户端 ID 和密钥。
4. 生成刷新令牌（播放控制所需）：获取刷新令牌有两种方法：选项 1：使用内置脚本
   npm run get-token
   这将启动本地服务器并在终端中提供指令。选项 2：使用简单脚本（如果选项 1 不起作用）
   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. 构建项目：
   npm run build

与 Claude Desktop 一起使用

1. 首先，确保 Spotify 已打开并在您的设备上播放
2. 将此服务器添加到您的 Claude Desktop 配置中：编辑您的claude_desktop_config.json文件（通常在 macOS 上位于~/Library/Application Support/Claude/中，或在 Windows 上位于%APPDATA%\\Claude\\中）：
   { "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桌面
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 Premium 帐户
• “刷新令牌问题” ：如果您的令牌已过期，请使用安装部分中的步骤生成一个新令牌

重要提示

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

执照

麻省理工学院