marcelmarais/Spotify

分类General

作者Community

星标867

定价Free

简介

这款 MCP 插件将 Spotify 的音乐控制能力直接接入 AI 助手，让 LLM 能够理解并执行你的听歌指令。它不再是简单的 API 调用，而是让 AI 成为你的智能音乐管家：你可以用自然语言要求它切换歌曲、管理播放列表或搜索特定曲风，而无需在多个 App 界面间切换。对于习惯在 IDE 或 AI 客户端中高效工作的开发者来说，这极大地降低了音乐管理的操作成本，上手简单，只需配置好 Spotify 凭据即可实现从对话到播放的无缝衔接。

核心亮点

用自然语言直接控制音乐播放与切换
高效管理个人歌单，无需手动操作界面
将 AI 助手转化为智能音乐搜索入口
快速配置，无缝集成至支持 MCP 的客户端

完整文档

<div align="center" style="display: flex; align-items: center; justify-content: center; gap: 10px;">
<img src="https://upload.wikimedia.org/wikipedia/commons/8/84/Spotify_icon.svg" width="30" height="30">
<h1>Spotify MCP Server</h1>
</div>

一个轻量级的 Model Context Protocol (MCP) 服务器，允许 Cursor 和 Claude 等 AI 助手控制 Spotify 播放并管理播放列表。

交互示例

工具

- 读取操作 - 专辑操作 - 播放/创建操作 - 播放列表操作

安装配置

- 前置条件 - 安装 - 创建 Spotify 开发者应用 - Spotify API 配置 - 身份验证流程

与 Claude Desktop, Cursor, 和 VsCode (Cline) 集成

</details>

交互示例

_"播放 Elvis 的第一首歌"_

_"创建一个 Taylor Swift 和 Slipknot 的融合播放列表"_

_"将我健身播放列表中的所有 techno 曲目复制到我的工作播放列表中"_

_"把音量调低一点"_

工具

读取操作

1. searchSpotify- Description: 在 Spotify 上搜索 track、album、artist 或 playlist
- Parameters:
- query (string): 搜索词
- type (string): 要搜索的项目类型 (track, album, artist, playlist)
- limit (number, optional): 返回结果的最大数量 (1-10, 默认值: 10)
- offset (number, optional): 返回结果的起始索引 (默认值: 0)
- Returns: 匹配项目的列表，包含其 ID、名称及详细信息
- Example: searchSpotify("bohemian rhapsody", "track", 10)

2. getNowPlaying

- Description: 获取 Spotify 当前正在播放的 track 信息，包括设备和音量信息
- Parameters: 无
- Returns: 包含 track 名称、artist、album、播放进度、时长、播放状态、设备信息、音量以及 shuffle/repeat 状态的对象
- Example: getNowPlaying()

3. getMyPlaylists

- Description: 获取当前用户在 Spotify 上的 playlist 列表
- Parameters:
- limit (number, optional): 返回 playlist 的最大数量 (默认值: 20)
- offset (number, optional): 返回 playlist 的起始索引 (默认值: 0)
- Returns: playlist 数组，包含其 ID、名称、track 数量和公开状态
- Example: getMyPlaylists(10, 0)

4. getPlaylistTracks- Description: 获取指定 Spotify playlist 的曲目列表
- Parameters:
- playlistId (string): playlist 的 Spotify ID
- limit (number, optional): 返回曲目的最大数量（默认值：100）
- offset (number, optional): 返回的第一首曲目的索引（默认值：0）
- Returns: 包含曲目 ID、名称、艺术家、专辑、时长和添加日期的曲目数组
- Example: getPlaylistTracks("37i9dQZEVXcJZyENOWUFo7")

5. getRecentlyPlayed

- Description: 获取 Spotify 最近播放的曲目列表。
- Parameters:
- limit (number, optional): 指定返回曲目的最大数量。
- Returns: 如果找到曲目，则返回格式化后的最近播放曲目列表；否则返回消息："You don't have any recently played tracks on Spotify"。
- Example: getRecentlyPlayed({ limit: 10 })

6. getUsersSavedTracks

- Description: 获取用户“Liked Songs”库中保存的曲目列表
- Parameters:
- limit (number, optional): 返回曲目的最大数量（1-50，默认值：50）
- offset (number, optional): 分页偏移量（从 0 开始的索引，默认值：0）
- Returns: 格式化后的保存曲目列表，包含曲目名称、艺术家、时长、曲目 ID 以及添加到 Liked Songs 的时间。显示分页信息（例如 "1-20 of 150"）。
- Example: getUsersSavedTracks({ limit: 20, offset: 0 })7. getQueue

- 描述: 获取 Spotify 队列中当前正在播放的曲目和即将播放的项目
- 参数:
- limit (number, 可选): 显示即将播放项目的最大数量 (1-50, 默认值: 10)
- 返回值: 当前播放的曲目以及队列中即将播放的曲目列表
- 示例: getQueue({ limit: 20 })

8. getAvailableDevices

- 描述: 获取用户可用 Spotify Connect 设备的信息
- 参数: 无
- 返回值: 可用设备列表，包含名称、类型、激活状态、音量和 device ID
- 示例: getAvailableDevices()

9. removeUsersSavedTracks

- 描述: 从用户的“ Liked Songs”库中移除一条或多条曲目（每次请求最多 40 条）
- 参数:
- trackIds (array): 要移除的 Spotify track IDs 数组（最多 40 个）
- 返回值: 成功确认消息
- 示例: removeUsersSavedTracks({ trackIds: ["4iV5W9uYEdYUVa79Axb7Rh", "1301WleyT98MSxVHPZCA6M"] })

Play / Create Operations

1. playMusic- Description: 在 Spotify 上开始播放曲目、专辑、艺术家或播放列表
- Parameters:
- uri (string, optional): 要播放项目的 Spotify URI（覆盖 type 和 id）
- type (string, optional): 要播放项目的类型 (track, album, artist, playlist)
- id (string, optional): 要播放项目的 Spotify ID
- deviceId (string, optional): 播放设备的 ID
- Returns: 成功状态
- Example: playMusic({ uri: "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" })
- Alternative: playMusic({ type: "track", id: "6rqhFgbbKwnb9MLmUQDhG6" })

2. pausePlayback

- Description: 暂停 Spotify 当前播放的曲目
- Parameters:
- deviceId (string, optional): 要暂停的设备 ID
- Returns: 成功状态
- Example: pausePlayback()

3. resumePlayback

- Description: 在活动设备上恢复 Spotify 播放
- Parameters:
- deviceId (string, optional): 恢复播放的设备 ID
- Returns: 成功状态
- Example: resumePlayback()

4. skipToNext

- Description: 跳到当前播放队列中的下一曲目
- Parameters:
- deviceId (string, optional): 设备 ID
- Returns: 成功状态
- Example: skipToNext()

5. skipToPrevious- Description: 跳至当前播放队列中的上一首曲目
- Parameters:
- deviceId (string, optional): 设备 ID
- Returns: 成功状态
- Example: skipToPrevious()

6. createPlaylist

- Description: 在 Spotify 上创建新播放列表
- Parameters:
- name (string): 新播放列表的名称
- description (string, optional): 播放列表的描述
- public (boolean, optional): 播放列表是否公开（默认：false）
- Returns: 包含新播放列表 ID 和 URL 的对象
- Example: createPlaylist({ name: "Workout Mix", description: "Songs to get pumped up", public: false })

7. addTracksToPlaylist

- Description: 向现有的 Spotify 播放列表添加曲目
- Parameters:
- playlistId (string): 播放列表 ID
- trackUris (array): 要添加的曲目 URI 或 ID 数组
- position (number, optional): 插入曲目的位置
- Returns: 成功状态和 snapshot ID
- Example: addTracksToPlaylist({ playlistId: "3cEYpjA9oz9GiPac4AsH4n", trackUris: ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh"] })

8. addToQueue- Description: 将曲目、专辑、艺术家或播放列表添加到当前播放队列
- Parameters:
- uri (string, optional): 要添加到队列的项目的 Spotify URI（覆盖 type 和 id）
- type (string, optional): 要入队的项目类型 (track, album, artist, playlist)
- id (string, optional): 要入队的项目的 Spotify ID
- deviceId (string, optional): 要执行入队操作的设备 ID
- Returns: 成功状态
- Example: addToQueue({ uri: "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" })
- Alternative: addToQueue({ type: "track", id: "6rqhFgbbKwnb9MLmUQDhG6" })

9. setVolume

- Description: 将播放音量设置为特定百分比（需要 Spotify Premium）
- Parameters:
- volumePercent (number): 要设置的音量 (0-100)
- deviceId (string, optional): 要设置音量的设备 ID
- Returns: 包含新音量级别的成功状态
- Example: setVolume({ volumePercent: 50 })

10. adjustVolume- Description: 相对调整播放音量（需要 Spotify Premium）
- Parameters:
- adjustment (number): 音量调整幅度 (-100 到 100)。正值增加音量，负值降低音量。
- deviceId (string, optional): 要调整音量的设备 ID
- Returns: 显示音量变化的成功状态（例如 "Volume increased from 50% to 60%"）
- Example: adjustVolume({ adjustment: 10 }) (增加 10%)
- Example: adjustVolume({ adjustment: -20 }) (降低 20%)

Album Operations

1. getAlbums

- Description: 通过 Spotify ID 获取一个或多个专辑的详细信息
- Parameters:
- albumIds (string|array): 单个专辑 ID 或专辑 ID 数组（最多 20 个）
- Returns: 专辑详情，包括名称、艺术家、发行日期、类型、总曲目数和 ID。单个专辑返回详细视图，多个专辑返回摘要列表。
- Example: getAlbums("4aawyAB9vmqN3uQ7FjRGTy") 或 getAlbums(["4aawyAB9vmqN3uQ7FjRGTy", "1DFixLWuPkv3KT3TnV35m3"])

2. getAlbumTracks- Description: 获取指定 album 的曲目，支持分页
- Parameters:
- albumId (string): album 的 Spotify ID
- limit (number, optional): 返回曲目的最大数量 (1-50)
- offset (number, optional): 分页偏移量 (从 0 开始的索引)
- Returns: 该 album 的曲目列表，包含曲目名称、艺术家、时长和 ID。显示分页信息。
- Example: getAlbumTracks("4aawyAB9vmqN3uQ7FjRGTy", 10, 0)

3. saveOrRemoveAlbumForUser

- Description: 将 album 保存到或从用户的 "Your Music" 库中移除
- Parameters:
- albumIds (array): Spotify album ID 数组 (最多 20 个)
- action (string): 执行的操作："save" 或 "remove"
- Returns: 包含确认消息的成功状态
- Example: saveOrRemoveAlbumForUser(["4aawyAB9vmqN3uQ7FjRGTy"], "save")

4. checkUsersSavedAlbums

- Description: 检查 album 是否已保存到用户的 "Your Music" 库中
- Parameters:
- albumIds (array): 要检查的 Spotify album ID 数组 (最多 20 个)
- Returns: 每个 album 的状态 (已保存或未保存)
- Example: checkUsersSavedAlbums(["4aawyAB9vmqN3uQ7FjRGTy", "1DFixLWuPkv3KT3TnV35m3"])

Playlist Operations

1. getPlaylist- Description: 获取特定 Spotify playlist 的详细信息，包括 tracks 数量、description 和 owner
- Parameters:
- playlistId (string): playlist 的 Spotify ID
- Returns: Playlist 名称、owner、track 数量、visibility、description、ID 和 URL
- Example: getPlaylist({ playlistId: "37i9dQZEVXcJZyENOWUFo7" })

2. updatePlaylist

- Description: 更新 Spotify playlist 的详细信息（name、description、public/private、collaborative）
- Parameters:
- playlistId (string): playlist 的 Spotify ID
- name (string, optional): playlist 的新名称
- description (string, optional): playlist 的新描述
- public (boolean, optional): playlist 是否公开
- collaborative (boolean, optional): playlist 是否为协作模式（要求 public 为 false）
- Returns: 包含已更新字段列表的成功确认
- Example: updatePlaylist({ playlistId: "3cEYpjA9oz9GiPac4AsH4n", name: "New Name", public: true })

3. removeTracksFromPlaylist- Description: 从 Spotify 播放列表中删除一条或多条曲目（每次请求最多 100 条）
- Parameters:
- playlistId (string): 播放列表的 Spotify ID
- trackIds (array): 要删除的 Spotify 曲目 ID 数组（最多 100 个）
- snapshotId (string, optional): 播放列表快照 ID，用于指定特定版本
- Returns: 包含删除曲目数量的成功确认
- Example: removeTracksFromPlaylist({ playlistId: "3cEYpjA9oz9GiPac4AsH4n", trackIds: ["4iV5W9uYEdYUVa79Axb7Rh"] })

4. reorderPlaylistItems

- Description: 通过将 Spotify 播放列表中的一段曲目移动到新位置来重新排序
- Parameters:
- playlistId (string): 播放列表的 Spotify ID
- rangeStart (number): 要移动的第一项的位置（从 0 开始的索引）
- insertBefore (number): 项应插入的位置（从 0 开始的索引）
- rangeLength (number, optional): 要移动的连续项数量（默认为 1）
- snapshotId (string, optional): 播放列表快照 ID，用于指定特定版本
- Returns: 包含移动详情的成功确认
- Example: reorderPlaylistItems({ playlistId: "3cEYpjA9oz9GiPac4AsH4n", rangeStart: 2, insertBefore: 0 })

Setup

Prerequisites

Node.js v16+

Spotify Premium 账户

已注册的 Spotify Developer 应用程序

Installation

bash

git clone https://github.com/marcelmarais/spotify-mcp-server.git


cd spotify-mcp-server
npm install
npm run build

### 创建 Spotify Developer Application

1. 访问 Spotify Developer Dashboard
2. 使用你的 Spotify 账号登录
3. 点击 "Create an App" 按钮
4. 填写 app 名称和描述
5. 同意 Terms of Service 并点击 "Create"
6. 在新 app 的 dashboard 中，你可以看到 Client ID
7. 点击 "Show Client Secret" 以显示 Client Secret
8. 点击 "Edit Settings" 并添加 Redirect URI（例如 http://127.0.0.1:8888/callback）
9. 保存更改

Spotify API 配置

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

bash

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

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

json

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

### 身份验证流程

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

1. 运行身份验证脚本：

bash

npm run auth

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

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

4. 授权后，Spotify 将将您重定向到指定的 redirect URI，且 URL 中会包含一个 code 参数。

5. 认证脚本将自动将此 code 兑换为 access token 和 refresh token。

6. 这些 token 将保存到您的 spotify-config.json 文件中，其内容将类似于：

json

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

注意：expiresAt 字段是一个 Unix 时间戳（毫秒），表示 access token 的过期时间。

7. 自动 Token 刷新：服务器将在 access token 过期时（通常为 1 小时后）自动刷新。刷新过程通过 refreshToken 透明完成，因此您无需手动重新认证。如果刷新失败，您需要再次运行 npm run auth 进行重新认证。

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

要在 Claude Desktop 中使用您的 MCP server，请将其添加到 Claude 配置中：

json

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

对于 Cursor，请前往 Cursor Settings 中的 MCP 选项卡（command + shift + J）。使用此命令添加服务器：

bash

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

要将 MCP 正确配置在 Cline 中，请确保你的 cline_mcp_settings.json 文件配置如下：

json

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

你可以将额外的工具添加到 auto approval 数组中，以便在无需干预的情况下运行这些工具。

marcelmarais/Spotify

简介

核心亮点

完整文档

交互示例

工具

读取操作

Play / Create Operations

Album Operations

Playlist Operations

Setup

Prerequisites

Installation
bash
`git clone https://github.com/marcelmarais/spotify-mcp-server.git`

Spotify API 配置

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

扫码进交流群

marcelmarais/Spotify

简介

核心亮点

完整文档

交互示例

工具

读取操作

Play / Create Operations

Album Operations

Playlist Operations

Setup

Prerequisites

Installationbashgit clone https://github.com/marcelmarais/spotify-mcp-server.git

Spotify API 配置

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

扫码进交流群

Installation
bash
`git clone https://github.com/marcelmarais/spotify-mcp-server.git`

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