Spotify MCP 服务器

一个基于 Node.js 的服务器，集成了 Spotify Web API 和模型上下文协议 (MCP)，提供搜索、控制播放和管理 Spotify 内容的工具。它允许用户通过标准化的 MCP 接口，经由 stdio 传输，以编程方式与他们的 Spotify 帐户进行交互。

---

🧠 项目概览

名称： Spotify MCP 服务器 描述： 一个可编程的接口，将 Spotify Web API 与 MCP 标准连接起来，从而可以使用基于 JSON 的工具通过 stdio 实现搜索、播放控制和播放列表管理。 主要功能：

• 🔍 在 Spotify 上搜索曲目
• 🎵 检查当前播放状态
• ▶️ 通过 URI 播放特定曲目
• 📋 检索用户播放列表
• ⏸ 暂停正在进行的播放
• 🔐 使用 Spotify 进行 OAuth 身份验证
• 📉 处理 Spotify API 请求的速率限制

---

⚙️ 前提条件

• Node.js (建议 v16 或更高版本)
• 具有应用程序凭据的 Spotify 开发者帐户
• npm (Node 包管理器)

---

📦 安装步骤

# 1. 克隆存储库
git clone <repository-url>
cd spotify-mcp

# 2. 安装依赖项
npm install

# 3. 创建一个 .env 文件并添加以下内容：

SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
SPOTIFY_REDIRECT_URI=http://localhost:8888/callback

注意： 将 your_spotify_client_id 和 your_spotify_client_secret 替换为您的 Spotify 开发者应用程序凭据。重定向 URI 必须与您在 Spotify 应用程序设置中设置的 URI 匹配。

# 4. 构建
npm run build
# 5. 运行服务器
npm start

这将打开一个浏览器进行 Spotify 身份验证，并使用 stdio 传输启动服务器。

---

🔧 工具

1. search_tracks

• 描述： 根据查询字符串在 Spotify 上搜索曲目。
• 输入模式：
  • query (字符串，必需)：搜索词（例如，艺术家姓名、歌曲标题）。
• 输出： 最多包含 5 个曲目对象的 JSON 数组，其中包含 name、artist、album、release_date、popularity、id 和 uri。
• 示例：

{
  "name": "search_tracks",
  "arguments": {"query": "The Beatles"}
}

2. get_playback_state

• 描述： 检索用户 Spotify 帐户的当前播放状态。
• 输入模式： 无
• 输出： 包含当前曲目信息、播放状态和设备详细信息的 JSON 对象，如果没有任何内容正在播放，则返回“No active playback”。
• 示例：

{
  "name": "get_playback_state",
  "arguments": {}
}

3. play_track

• 描述： 使用其 Spotify URI 播放特定曲目。
• 输入模式：
  • uri (字符串，必需)：Spotify 曲目 URI（例如，spotify:track:xxx）。
• 输出： 包含 status 和 uri 的 JSON 确认。
• 示例：

{
  "name": "play_track",
  "arguments": {"uri": "spotify:track:7KXjTSCq5nL1LoYtL7XAwS"}
}

4. get_user_playlists

• 描述： 从 Spotify 获取用户的播放列表。
• 输入模式：
  • limit (数字，可选)：要返回的最大播放列表数量（默认值：20）。
• 输出： 包含 name、id、track_count、uri 和 public 状态的播放列表对象的 JSON 数组。
• 示例：

{
  "name": "get_user_playlists",
  "arguments": {"limit": 10}
}

5. pause_playback

• 描述： 暂停用户活动 Spotify 设备上的当前播放。
• 输入模式： 无
• 输出： 包含“Playback paused”状态的 JSON 确认。
• 示例：

{
  "name": "pause_playback",
  "arguments": {}
}

---

🌐 使用案例

1. 音乐发现机器人：

   • 使用 search_tracks 和 play_track 来实现基于心情的音乐聊天机器人。

2. 播放列表管理工具：

   • 使用 get_user_playlists 和 search_tracks 来预览和组织播放列表。

3. 播放控制自动化：

   • 使用 get_playback_state、play_track 和 pause_playback 自动化播放操作。

4. Spotify 仪表板：

   • 使用 get_playback_state、get_user_playlists、pause_playback 和 play_track 构建桌面小部件。

5. 学习 Spotify API：

   • 尝试所有工具来了解 Spotify Web API 的工作原理。

---

🔐 身份验证详细信息

• 首次运行时，服务器会打开一个浏览器进行 Spotify OAuth 身份验证。
• 通过 http://localhost:8888/callback 接收代码。
• 将代码交换为访问令牌和刷新令牌。
• 在到期前 5 分钟内自动刷新令牌。

---

⏱ 速率限制

• 使用重试策略处理 Spotify API 速率限制：
  • 每次请求后冷却 10 秒。
  • 如果发生 429 Too Many Requests 错误，则等待 1 分钟。

---

📊 依赖项

npm install dotenv spotify-web-api-node @modelcontextprotocol/sdk open

• dotenv：从 .env 加载环境变量。
• spotify-web-api-node：Spotify API 客户端。
• @modelcontextprotocol/sdk：实现 MCP 服务器。
• http, url：Node.js 内置的 OAuth 重定向服务器。
• open：打开默认浏览器进行身份验证。

---

📁 开发信息

• 入口点： index.js
• 语言： JavaScript (带有 ES 模块的 Node.js)
• 运行命令： node index.js
• 调试： 检查控制台日志以查找 MCP 或身份验证错误。

---

⚠️ 限制

• 播放控制需要 Spotify Premium。
• 仅支持 stdio 传输（没有 HTTP、WebSocket 等）。
• search_tracks 最多返回 5 个结果。
• 假设只有一个活动设备用于播放。

---

🚀 贡献

请随时打开 issue 或提交 pull request 以：

• 添加新工具
• 增强现有功能
• 改进文档

---

✍️ 许可证

MIT 许可证 - 可以免费使用、修改和分发以用于个人或商业用途。

---

❤️ 页脚

由 Rakshitha C Devadiga 于 2025 年 3 月 17 日用 ❤️ 构建