Spotify MCP Server (Marcelmarais)

Spotify MCP Server

轻量级 模型上下文协议（MCP） 该服务器使Cursor&Claude等人工智能助手能够控制Spotify的播放和管理播放列表。

Contents

• 交互示例
• 工具

- 读取操作 - 相册操作 - 播放/创建操作 - 播放列表操作

• 设置

- 先决条件 - 安装 - 创建Spotify开发者应用程序 - Spotify API配置 - 验证过程

• 与Claude Desktop、Cursor和VsCode（Cline）集成

交互示例

• _“播放埃尔维斯的第一首歌”_
• _“创建Taylor Swift/Slipknot融合播放列表”_
• _“将我的锻炼播放列表中的所有techno曲目复制到我的工作播放列表中”_
• _“把音量调低一点”_

工具

读取操作

1. 搜索Spotify

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

1. 立即开始播放

- 描述：获取有关Spotify上当前播放曲目的信息，包括设备和音量信息 - 参数：无 - 退货：包含曲目名称、艺术家、专辑、播放进度、持续时间、播放状态、设备信息、音量和随机播放/重复状态的对象 - 示例: getNowPlaying()

1. 获取我的播放列表

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

1. 可用

- 描述：获取特定Spotify播放列表中的曲目列表 - 参数: - playlistId （string）：播放列表的Spotify ID - limit （数字，可选）：要返回的最大曲目数（默认值：100） - offset （数字，可选）：要返回的第一个曲目的索引（默认值：0） - 退货：包含ID、姓名、艺术家、专辑、持续时间和添加日期的曲目数组 - 示例: getPlaylistTracks("37i9dQZEVXcJZyENOWUFo7")

1. 最近播放

- 描述：从Spotify检索最近播放的曲目列表。 - 参数: - limit （number，可选）：指定要返回的最大曲目数的数字。 - 退货：如果找到曲目，它会返回最近播放的曲目的格式化列表，否则会显示一条消息：“您在Spotify上没有最近播放的任何曲目”。 - 示例: getRecentlyPlayed({ limit: 10 })

1. getUsersSavedTracks

- 描述：获取用户“喜欢的歌曲”库中保存的曲目列表 - 参数: - limit （数字，可选）：要返回的最大曲目数（1-50，默认值：50） - offset （数字，可选）：分页偏移量（基于0的索引，默认值：0） - 退货：已保存曲目的格式化列表，包括曲目名称、艺术家、持续时间、曲目ID以及何时添加到喜欢的歌曲中。显示分页信息（例如，“150中的1-20”）。 - 示例: getUsersSavedTracks({ limit: 20, offset: 0 })

1. getQueue

- 描述：获取Spotify队列中当前播放的曲目和即将播放的项目 - 参数: - limit （数字，可选）：即将显示的项目的最大数量（1-50，默认值：10） - 退货：当前播放的曲目和队列中即将播放的曲目列表 - 示例: getQueue({ limit: 20 })

1. 获取可用设备

- 描述：获取有关用户可用的Spotify Connect设备的信息 - 参数：无 - 退货：可用设备列表，包括名称、类型、活动状态、音量和设备ID - 示例: getAvailableDevices()

1. remove用户保存的机架

- 描述：从用户的“喜欢的歌曲”库中删除一首或多首曲目（每次请求最多40首） - 参数: - trackIds （array）：要删除的Spotify曲目ID数组（最多40个） - 退货：成功确认消息 - 示例: removeUsersSavedTracks({ trackIds: ["4iV5W9uYEdYUVa79Axb7Rh", "1301WleyT98MSxVHPZCA6M"] })

播放/创建操作

1. play音乐

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

1. 编辑

- 描述：暂停Spotify上当前播放的曲目 - 参数: - deviceId （字符串，可选）：要暂停的设备的ID - 退货：成功状态 - 示例: pausePlayback()

1. resume回放

- 描述：在活动设备上恢复Spotify播放 - 参数: - deviceId （字符串，可选）：要恢复播放的设备的ID - 退货：成功状态 - 示例: resumePlayback()

1. 跳过下一步

- 描述：跳到当前播放队列中的下一首曲目 - 参数: - deviceId （字符串，可选）：设备的ID - 退货：成功状态 - 示例: skipToNext()

1. skipTo上一页

- 描述：跳到当前播放队列中的上一首曲目 - 参数: - deviceId （字符串，可选）：设备的ID - 退货：成功状态 - 示例: skipToPrevious()

1. 创建播放列表

- 描述：在Spotify上创建新的播放列表 - 参数: - name （string）：新播放列表的名称 - description （字符串，可选）：播放列表的描述 - public （布尔值，可选）：播放列表是否应公开（默认值：false） - 退货：具有新播放列表ID和URL的对象 - 示例: createPlaylist({ name: "Workout Mix", description: "Songs to get pumped up", public: false })

1. 添加trackstoplaylist

- 描述：将曲目添加到现有的Spotify播放列表 - 参数: - playlistId （string）：播放列表的ID - trackUris （array）：要添加的跟踪URI或ID的数组 - position （数字，可选）：插入轨迹的位置 - 退货：成功状态和快照ID - 示例: addTracksToPlaylist({ playlistId: "3cEYpjA9oz9GiPac4AsH4n", trackUris: ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh"] })

1. 添加队列

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

1. 设置

- 描述：将播放音量设置为特定百分比（需要Spotify Premium） - 参数: - volumePercent （数字）：要设置的音量（0-100） - deviceId （字符串，可选）：要设置音量的设备的ID - 退货：新音量级别的成功状态 - 示例: setVolume({ volumePercent: 50 })

1. 调整音量

• 描述：将播放音量调高或调低相对量（需要Spotify Premium）
• 参数:

- adjustment （number）：调整音量的量（-100到100）。正值增加体积，负值减少体积。 - deviceId （字符串，可选）：用于调节音量的设备的ID

• 退货：显示音量变化的成功状态（例如，“音量从50%增加到60%”）
• 示例: adjustVolume({ adjustment: 10 }) （增加10%）
• 示例: adjustVolume({ adjustment: -20 }) （减少20%）

相册操作

1. 获取相册

- 描述：通过Spotify ID获取一个或多个专辑的详细信息 - 参数: - albumIds （string | array）：单个专辑ID或专辑ID数组（最多20个） - 退货：专辑详细信息，包括姓名、艺术家、发行日期、类型、总曲目和ID。对于单张专辑返回详细视图，对于多张专辑返回摘要列表。 - 示例: getAlbums("4aawyAB9vmqN3uQ7FjRGTy") 或 getAlbums(["4aawyAB9vmqN3uQ7FjRGTy", "1DFixLWuPkv3KT3TnV35m3"])

1. getAlbumTracks

- 描述：从支持分页的特定专辑中获取曲目 - 参数: - albumId （string）：专辑的Spotify ID - limit （数量，可选）：要返回的最大曲目数量（1-50） - offset （数字，可选）：分页偏移量（基于0的索引） - 退货：专辑中包含曲目名称、艺术家、持续时间和ID的曲目列表。显示分页信息。 - 示例: getAlbumTracks("4aawyAB9vmqN3uQ7FjRGTy", 10, 0)

1. saveOrRemoveAlbumForUser

- 描述：从用户的“您的音乐”库中保存或删除相册 - 参数: - albumIds （数组）：Spotify专辑ID数组（最多20个） - action （string）：要执行的操作：“保存”或“删除” - 退货：带有确认消息的成功状态 - 示例: saveOrRemoveAlbumForUser(["4aawyAB9vmqN3uQ7FjRGTy"], "save")

1. checkUsers保存白蛋白

- 描述：检查相册是否保存在用户的“您的音乐”库中 - 参数: - albumIds （array）：要检查的Spotify专辑ID数组（最多20个） - 退货：每个相册的状态（已保存或未保存） - 示例: checkUsersSavedAlbums(["4aawyAB9vmqN3uQ7FjRGTy", "1DFixLWuPkv3KT3TnV35m3"])

播放列表操作

1. 获取播放列表

- 描述：获取特定Spotify播放列表的详细信息，包括曲目数量、描述和所有者 - 参数: - playlistId （string）：播放列表的Spotify ID - 退货：播放列表名称、所有者、曲目计数、可见性、描述、ID和URL - 示例: getPlaylist({ playlistId: "37i9dQZEVXcJZyENOWUFo7" })

1. 下载中

- 描述：更新Spotify播放列表的详细信息（名称、描述、公共/私人、协作） - 参数: - playlistId （string）：播放列表的Spotify ID - name （字符串，可选）：播放列表的新名称 - description （字符串，可选）：播放列表的新描述 - public （布尔值，可选）：播放列表是否应公开 - collaborative （布尔值，可选）：播放列表是否应该是协作的（要求public为false） - 退货：成功确认已更新字段列表 - 示例: updatePlaylist({ playlistId: "3cEYpjA9oz9GiPac4AsH4n", name: "New Name", public: true })

1. 从播放列表中删除曲目

- 描述：从Spotify播放列表中删除一首或多首曲目（每次请求最多100首曲目） - 参数: - playlistId （string）：播放列表的Spotify ID - trackIds （array）：要删除的Spotify曲目ID数组（最多100个） - snapshotId （字符串，可选）：针对特定版本的播放列表快照ID - 退货：成功确认已删除曲目数量 - 示例: removeTracksFromPlaylist({ playlistId: "3cEYpjA9oz9GiPac4AsH4n", trackIds: ["4iV5W9uYEdYUVa79Axb7Rh"] })

1. 重新排序播放列表项目

- 描述：通过将Spotify播放列表中的一系列曲目移动到新位置，对其进行重新排序 - 参数: - playlistId （string）：播放列表的Spotify ID - rangeStart （数字）：要移动的第一个项目的位置（从0开始的索引） - insertBefore （数字）：应插入项目的位置（从0开始的索引） - rangeLength （number，可选）：要移动的连续项目数（默认为1） - snapshotId （字符串，可选）：针对特定版本的播放列表快照ID - 退货：使用移动详细信息确认成功 - 示例: reorderPlaylistItems({ playlistId: "3cEYpjA9oz9GiPac4AsH4n", rangeStart: 2, insertBefore: 0 })

设置

先决条件

• 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://127.0.0.1:8888/callback)
9. 保存您的更改

Spotify API配置

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

# Copy the example config file
cp spotify-config.example.json spotify-config.json

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

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

验证过程

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

1. 运行身份验证脚本：

npm run auth

1. 该脚本将生成一个授权URL。请在web浏览器中打开此URL。

1. 系统将提示您登录Spotify并授权您的应用程序。

1. 授权后，Spotify将使用URL中的代码参数将您重定向到指定的重定向URI。

1. 身份验证脚本将自动将此代码交换为访问和刷新令牌。

1. 这些令牌将保存到您的 spotify-config.json 文件，现在看起来像：

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

备注：The expiresAt 字段是Unix时间戳（以毫秒为单位），指示访问令牌何时过期。

1. 自动令牌刷新：服务器将在访问令牌过期时（通常在1小时后）自动刷新访问令牌。使用 refreshToken，因此您不需要手动重新进行身份验证。如果刷新失败，您需要运行 npm run auth 再次进行重新认证。

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

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

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

对于光标，请转到中的MCP选项卡 Cursor Settings （命令+换档+J）。使用以下命令添加服务器：

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

要使用Cline正确设置MCP，请确保您已设置以下文件配置 cline_mcp_settings.json:

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

您可以将其他工具添加到自动审批数组中，以便在不进行干预的情况下运行这些工具。