Spotify MCP Server

<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) 服务器，使 AI 助手（如 Cursor 和 Claude）能够控制 Spotify 播放并管理播放列表。

<details> <summary>目录</summary>

• 示例交互
• 工具
  • 读取操作
  • 播放 / 创建操作
• 设置
  • 先决条件
  • 安装
  • 创建 Spotify 开发者应用程序
  • Spotify API 配置
  • 身份验证过程
• 与 Claude Desktop 和 Cursor 集成

</details>

示例交互

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

工具

读取操作

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")

播放 / 创建操作

1. playMusic

   • 描述: 在 Spotify 上开始播放曲目、专辑、艺术家或播放列表
   • 参数:
     • uri (字符串，可选): 要播放的项目的 Spotify URI（覆盖 type 和 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（覆盖 type 和 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。 在您的 Web 浏览器中打开此 URL。

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

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

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 集成

要将您的 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