Spotify MCP 服务器

Name: Spotify MCP 服务器
Author: marcelmarais

作者：marcelmarais186 星标更新：2025-11-17

项目介绍

<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 服务器</h1> </div>

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

示例交互
工具
设置
与 Claude Desktop、Cursor 和 VsCode (Cline) 集成

</details>

示例交互

"播放 Elvis 的第一首歌"
"创建 Taylor Swift / Slipknot 融合播放列表"
"将我的健身播放列表中的所有 techno 曲目复制到我的工作播放列表中"

工具

读取操作

searchSpotify
- 描述：在 Spotify 上搜索曲目、专辑、艺术家或播放列表
- 参数：
  - query (字符串)：搜索词
  - type (字符串)：要搜索的项目类型（曲目、专辑、艺术家、播放列表）
  - limit (数字，可选)：返回结果的最大数量（10-50）
- 返回值：匹配项及其ID、名称和附加详情的列表
- 示例：searchSpotify("bohemian rhapsody", "track", 20)
getNowPlaying
- 描述：获取当前正在播放的曲目的信息
- 参数：无
- 返回值：包含曲目名称、艺术家、专辑、播放进度、时长和播放状态的对象
- 示例：getNowPlaying()
getMyPlaylists
- 描述：获取当前用户在 Spotify 上的播放列表列表
- 参数：
  - limit (数字，可选)：返回播放列表的最大数量（默认：20）
  - offset (数字，可选)：返回的第一个播放列表的索引（默认：0）
- 返回值：包含播放列表ID、名称、曲目数量和公开状态的播放列表数组
- 示例：getMyPlaylists(10, 0)
getPlaylistTracks
- 描述：获取特定 Spotify 播放列表中的曲目列表
- 参数：
  - playlistId (字符串)：播放列表的 Spotify ID
  - limit (数字，可选)：返回曲目的最大数量（默认：100）
  - offset (数字，可选)：返回的第一个曲目的索引（默认：0）
- 返回值：包含曲目ID、名称、艺术家、专辑、时长和添加日期的曲目数组
- 示例：getPlaylistTracks("37i9dQZEVXcJZyENOWUFo7")
getRecentlyPlayed
- 描述：从 Spotify 获取最近播放的曲目列表。
- 参数：
  - limit (数字，可选)：指定返回的最大曲目数量。
- 返回值：如果找到曲目，则返回格式化的最近播放曲目列表；否则返回消息：“您没有最近在 Spotify 上播放的曲目”。
- 示例：getRecentlyPlayed({ limit: 1 0})
getUsersSavedTracks
- 描述：获取保存在用户“我喜欢的歌曲”库中的曲目列表
- 参数：
  - limit (数字，可选)：返回曲目的最大数量（1-50，默认：50）
  - offset (数字，可选)：分页的偏移量（基于0的索引，默认：0）
- 返回值：格式化的已保存曲目列表，包括曲目名称、艺术家、时长、曲目ID以及它们被添加到“我喜欢的歌曲”的时间。显示分页信息（例如，“1-20 of 150”）。
- 示例：getUsersSavedTracks({ limit: 20, offset: 0 })

播放/创建操作

playMusic
- 描述：开始在 Spotify 上播放曲目、专辑、艺术家或播放列表
- 参数：
  - uri (字符串，可选)：要播放项目的 Spotify URI（覆盖 type 和 id）
  - type (字符串，可选)：要播放的项目类型（曲目、专辑、艺术家、播放列表）
  - id (字符串，可选)：要播放项目的 Spotify ID
  - deviceId (字符串，可选)：播放设备的ID
- 返回值：成功状态
- 示例：playMusic({ uri: "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" })
- 替代方案：playMusic({ type: "track", id: "6rqhFgbbKwnb9MLmUQDhG6" })
pausePlayback
- 描述：暂停当前正在播放的曲目
- 参数：
  - deviceId (字符串，可选)：暂停设备的ID
- 返回值：成功状态
- 示例：pausePlayback()
skipToNext
- 描述：跳到当前播放队列中的下一曲目
- 参数：
  - deviceId (字符串，可选)：设备ID
- 返回值：成功状态
- 示例：skipToNext()
skipToPrevious
- 描述：跳到当前播放队列中的上一曲目
- 参数：
  - deviceId (字符串，可选)：设备ID
- 返回值：成功状态
- 示例：skipToPrevious()
createPlaylist
- 描述：在 Spotify 上创建新的播放列表
- 参数：
  - name (字符串)：新播放列表的名称
  - description (字符串，可选)：播放列表的描述
  - public (布尔值，可选)：播放列表是否公开（默认：false）
- 返回值：包含新播放列表ID和URL的对象
- 示例：createPlaylist({ name: "Workout Mix", description: "激励歌曲", public: false })
addTracksToPlaylist
- 描述：向现有的 Spotify 播放列表添加曲目
- 参数：
  - playlistId (字符串)：播放列表的ID
  - trackUris (数组)：要添加的曲目URI或ID数组
  - position (数字，可选)：插入曲目的位置
- 返回值：成功状态和快照ID
- 示例：addTracksToPlaylist({ playlistId: "3cEYpjA9oz9GiPac4AsH4n", trackUris: ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh"] })
addToQueue
- 描述：将曲目、专辑、艺术家或播放列表添加到当前播放队列
- 参数：
  - uri (字符串，可选)：要添加到队列的项目的 Spotify URI（覆盖 type 和 id）
  - type (字符串，可选)：要排队的项目类型（曲目、专辑、艺术家、播放列表）
  - id (字符串，可选)：要排队项目的 Spotify ID
  - deviceId (字符串，可选)：排队设备的ID
- 返回值：成功状态
- 示例：addToQueue({ uri: "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" })
- 替代方案：addToQueue({ type: "track", id: "6rqhFgbbKwnb9MLmUQDhG6" })

专辑操作

getAlbums
- 描述：通过 Spotify ID 获取一个或多个专辑的详细信息
- 参数：
  - albumIds (字符串或数组)：单个专辑ID或专辑ID数组（最多20个）
- 返回值：专辑详情，包括名称、艺术家、发行日期、类型、总曲目数和ID。对于单个专辑返回详细视图，对于多个专辑返回摘要列表。
- 示例：getAlbums("4aawyAB9vmqN3uQ7FjRGTy") 或 getAlbums(["4aawyAB9vmqN3uQ7FjRGTy", "1DFixLWuPkv3KT3TnV35m3"])
getAlbumTracks
- 描述：从特定专辑获取曲目，支持分页
- 参数：
  - albumId (字符串)：专辑的 Spotify ID
  - limit (数字，可选)：返回曲目的最大数量（1-50）
  - offset (数字，可选)：分页的偏移量（基于0的索引）
- 返回值：专辑中的曲目列表，包括曲目名称、艺术家、时长和ID。显示分页信息。
- 示例：getAlbumTracks("4aawyAB9vmqN3uQ7FjRGTy", 10, 0)
saveOrRemoveAlbumForUser
- 描述：保存或删除用户的“我的音乐”库中的专辑
- 参数：
  - albumIds (数组)：要保存或删除的 Spotify 专辑ID数组（最多20个）
  - action (字符串)：执行的操作：“save”或“remove”
- 返回值：带有确认消息的成功状态
- 示例：saveOrRemoveAlbumForUser(["4aawyAB9vmqN3uQ7FjRGTy"], "save")
checkUsersSavedAlbums
- 描述：检查专辑是否保存在用户的“我的音乐”库中
- 参数：
  - albumIds (数组)：要检查的 Spotify 专辑ID数组（最多20个）
- 返回值：每个专辑的状态（已保存或未保存）
- 示例：checkUsersSavedAlbums(["4aawyAB9vmqN3uQ7FjRGTy", "1DFixLWuPkv3KT3TnV35m3"])

设置

先决条件

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 开发者应用

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

Spotify API 配置

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

# 复制示例配置文件
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 进行认证。按照以下步骤进行应用认证：

运行认证脚本：

npm run auth

脚本将生成一个授权URL。在您的网络浏览器中打开此URL。
您将被提示登录 Spotify 并授权您的应用。
授权后，Spotify 将将您重定向到您指定的重定向URI，并在URL中带有代码参数。
认证脚本将自动交换此代码以换取访问和刷新令牌。
这些令牌将保存到您的 spotify-config.json 文件中，现在看起来像这样：

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

当需要时，服务器将自动使用刷新令牌刷新访问令牌。

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

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

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

对于 Cursor，转到 Cursor 设置 中的 MCP 标签（命令 + shift + 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"]
    }
  }
}

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