Spotify MCP 服务器

一个轻量级的 模型上下文协议 (MCP) 服务器，使像 Cursor 和 Claude 这样的 AI 助手能够控制 Spotify 播放并管理播放列表。

示例交互

• "播放 Elvis 的第一首歌"
• "创建一个 Taylor Swift / Slipknot 融合播放列表"
• "将我的锻炼播放列表中的所有电子音乐曲目复制到我的工作播放列表中"

工具

读取操作

1. searchSpotify

   • 描述: 在 Spotify 上搜索曲目、专辑、艺术家或播放列表
   • 参数:
     • query (字符串): 搜索词
     • type (字符串): 要搜索的项目类型（曲目、专辑、艺术家、播放列表）
     • limit (数字, 可选): 返回的最大结果数（10-50）
   • 返回: 匹配项目的列表，包括它们的 ID、名称和其他详细信息
   • 示例: searchSpotify("bohemian rhapsody", "track", 20)

2. getNowPlaying

   • 描述: 获取当前在 Spotify 上播放的曲目信息
   • 参数: 无
   • 返回: 包含曲目名称、艺术家、专辑、播放进度、时长和播放状态的对象
   • 示例: getNowPlaying()

3. getMyPlaylists

   • 描述: 获取当前用户在 Spotify 上的播放列表
   • 参数:
     • limit (数字, 可选): 返回的最大播放列表数（默认: 20）
     • offset (数字, 可选): 要返回的第一个播放列表的索引（默认: 0）
   • 返回: 播放列表数组，包括它们的 ID、名称、曲目数量和公开状态
   • 示例: getMyPlaylists(10, 0)

4. getPlaylistTracks

   • 描述: 获取特定 Spotify 播放列表中的曲目列表
   • 参数:
     • playlistId (字符串): 播放列表的 Spotify ID
     • limit (数字, 可选): 返回的最大曲目数（默认: 100）
     • offset (数字, 可选): 要返回的第一个曲目的索引（默认: 0）
   • 返回: 曲目数组，包括它们的 ID、名称、艺术家、专辑、时长和添加日期
   • 示例: getPlaylistTracks("37i9dQZEVXcJZyENOWUFo7")

5. getRecentlyPlayed

   • 描述: 从 Spotify 获取最近播放的曲目列表。
   • 参数:
     • limit (数字, 可选): 指定要返回的最大曲目数。
   • 返回: 如果找到曲目，则返回最近播放曲目的格式化列表，否则返回消息："You don't have any recently played tracks on Spotify"。
   • 示例: getRecentlyPlayed({ limit: 10 })

6. getRecentlyPlayed

   • 描述: 从 Spotify 获取最近播放的曲目列表。
   • 参数:
     • limit (数字, 可选): 指定要返回的最大曲目数。
   • 返回: 如果找到曲目，则返回最近播放曲目的格式化列表，否则返回消息："You don't have any recently played tracks on Spotify"。
   • 示例: getRecentlyPlayed({ limit: 10 })

播放 / 创建操作

1. playMusic

   • 描述: 开始播放 Spotify 上的曲目、专辑、艺术家或播放列表
   • 参数:
     • uri (字符串, 可选): 要播放的项目的 Spotify URI（覆盖类型和 ID）
     • type (字符串, 可选): 要播放的项目类型（曲目、专辑、艺术家、播放列表）
     • id (字符串, 可选): 要播放的项目的 Spotify ID
     • deviceId (字符串, 可选): 要播放的设备 ID
   • 返回: 成功状态
   • 示例: playMusic({ uri: "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" })
   • 替代方案: playMusic({ type: "track", id: "6rqhFgbbKwnb9MLmUQDhG6" })

2. pausePlayback

   • 描述: 暂停当前在 Spotify 上播放的曲目
   • 参数:
     • deviceId (字符串, 可选): 要暂停的设备 ID
   • 返回: 成功状态
   • 示例: pausePlayback()

3. skipToNext

   • 描述: 跳到当前播放队列中的下一首曲目
   • 参数:
     • deviceId (字符串, 可选): 设备 ID
   • 返回: 成功状态
   • 示例: skipToNext()

4. skipToPrevious

   • 描述: 跳到当前播放队列中的上一首曲目
   • 参数:
     • deviceId (字符串, 可选): 设备 ID
   • 返回: 成功状态
   • 示例: skipToPrevious()

5. createPlaylist

   • 描述: 在 Spotify 上创建一个新的播放列表
   • 参数:
     • name (字符串): 新播放列表的名称
     • description (字符串, 可选): 播放列表的描述
     • public (布尔值, 可选): 播放列表是否公开（默认: false）
   • 返回: 包含新播放列表 ID 和 URL 的对象
   • 示例: createPlaylist({ name: "Workout Mix", description: "Songs to get pumped up", public: false })

6. addTracksToPlaylist

   • 描述: 将曲目添加到现有的 Spotify 播放列表中
   • 参数:
     • playlistId (字符串): 播放列表的 ID
     • trackUris (数组): 要添加的曲目 URI 或 ID 的数组
     • position (数字, 可选): 插入曲目的位置
   • 返回: 成功状态和快照 ID
   • 示例: addTracksToPlaylist({ playlistId: "3cEYpjA9oz9GiPac4AsH4n", trackUris: ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh"] })

7. addToQueue

   • 描述: 将曲目、专辑、艺术家或播放列表添加到当前播放队列中
   • 参数:
     • uri (字符串, 可选): 要添加到队列的项目的 Spotify URI（覆盖类型和 ID）
     • type (字符串, 可选): 要排队项目的类型（曲目、专辑、艺术家、播放列表）
     • id (字符串, 可选): 要排队项目的 Spotify ID
     • deviceId (字符串, 可选): 要排队的设备 ID
   • 返回: 成功状态
   • 示例: addToQueue({ uri: "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" })
   • 替代方案: addToQueue({ type: "track", id: "6rqhFgbbKwnb9MLmUQDhG6" })

设置

先决条件

• Node.js v16+
• Spotify Premium 账户
• 已注册的 Spotify 开发者应用程序

安装

git clone https://github.com/marcelmarais/spotify-mcp-server.git
cd spotify-mcp-server
npm install
npm run build

创建 Spotify 开发者应用程序

1. 访问 Spotify 开发者仪表板
2. 使用您的 Spotify 账户登录
3. 点击“创建应用”按钮
4. 填写应用名称和描述
5. 接受服务条款并点击“创建”
6. 在您的新应用仪表板中，您将看到您的 客户端 ID
7. 点击“显示客户端密钥”以显示您的 客户端密钥
8. 点击“编辑设置”并添加一个重定向 URI（例如 http://localhost:8888/callback）
9. 保存您的更改

Spotify API 配置

在项目根目录中创建一个 spotify-config.json 文件（您可以复制并修改提供的示例）：

# 复制示例配置文件
cp spotify-config.example.json spotify-config.json

然后使用您的凭据编辑文件：

{
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "redirectUri": "http://localhost:8888/callback"
}

认证流程

Spotify API 使用 OAuth 2.0 进行认证。按照以下步骤认证您的应用程序：

1. 运行认证脚本：

npm run auth

2. 脚本将生成一个授权 URL。在您的网络浏览器中打开此 URL。

3. 您将被提示登录 Spotify 并授权您的应用程序。

4. 授权后，Spotify 会将您重定向到您指定的重定向 URI，并在 URL 中带有代码参数。

5. 认证脚本将自动将此代码交换为访问令牌和刷新令牌。

6. 这些令牌将保存到您的 spotify-config.json 文件中，文件现在将如下所示：

{
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "redirectUri": "http://localhost:8888/callback",
  "accessToken": "BQAi9Pn...kKQ",
  "refreshToken": "AQDQcj...7w",
  "expiresAt": 1677889354671
}

7. 服务器将在需要时自动使用刷新令牌刷新访问令牌。

与 Claude Desktop、Cursor 和 VsCode 通过 Cline 模型扩展 集成

要将您的 MCP 服务器与 Claude Desktop 一起使用，请将其添加到您的 Claude 配置中：

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["spotify-mcp-server/build/index.js"]
    }
  }
}

对于 Cursor，请转到 Cursor 设置 中的 MCP 选项卡（command + shift + J）。使用以下命令添加服务器：

node path/to/spotify-mcp-server/build/index.js

要正确设置您的 MCP 与 Cline，请确保您有以下文件配置 cline_mcp_settings.json：

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["~/../spotify-mcp-server/build/index.js"],
      "autoApprove": ["getListeningHistory", "getNowPlaying"]
    }
  }
}

您可以将其他工具添加到自动批准数组中，以无需干预地运行这些工具。