MCP Spotify Server (Jk Gzenna)

MCP Spotify Server

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

安全功能（令牌管理和刷新）

1. ### 'auth.ts'类，用于使用'npm run-auth'手动生成令牌

这 auth 类（以前 authTest.ts)允许通过运行命令手动生成令牌 npm run auth此过程生成 accessToken 和 refreshToken 基于 clientId 和 clientSecret 指定在 spotify-config.json 文件。用户在浏览器中确认后，令牌将在配置文件中更新。

1. ### 与AI客户端使用的名为“getAccessToken”的新MCP工具关联的“authApp.ts”类

这 getAccessToken 是一种新的MCP工具，使Claude、Cursor和VsCode等AI客户端能够以编程方式获取Spotify令牌。它使用 clientId 和 clientSecret 从 spotify-config.json 生成一个 accessToken 和 refreshToken用户在浏览器中确认Spotify授权后，用户将被重定向回AI客户端，浏览器通过重定向URI显示成功消息 http://127.0.0.1:8088，该工具会更新 spotify-config.json 使用新令牌（accessToken和refreshToken）的文件。

1. ### 与名为“refreshAccessToken”的新MCP工具关联的“refreshToken.ts”类

这 refreshAccessToken 是一个新的MCP工具，它使Claude、Cursor和VsCode等AI客户端能够使用refreshToken以编程方式刷新Spotify accessToken。它使用 refreshToken 从 spotify-config.json 生成新的accessToken 无需浏览器中的用户确认。 此MCP工具简化了令牌管理，并与MCP工作流程无缝集成，消除了手动干预的需要。

• ### “accessToken”终端查看和检查状态

您可以使用查看“accessToken”并检查其状态 sh spotify-check-token.sh 在项目根目录中提示的终端中。

交互示例

• _“获取新的访问令牌”_
• _“刷新访问令牌”_
• _“播放江南Style第一首歌”_
• _“创建Snoop Dog/El Fary融合播放列表”_
• _“将我的锻炼播放列表中的所有techno曲目复制到我的工作播放列表中”_

工具

读取操作

1. '搜索Spotify'

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

1. 'getNowPlaying'

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

1. '获取我的播放列表'

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

1. 'getPlaylistTracks'

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

1. '最近播放'

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

播放和创建操作

1. '播放音乐'

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

1. 'pause回放'

• 描述：暂停Spotify上当前播放的曲目
• 参数:

- deviceId （字符串，可选）：要暂停的设备的ID

• 退货：成功状态
• 示例: pausePlayback()

1. 跳转到下一步

• 描述：跳到当前播放队列中的下一首曲目
• 参数:

- deviceId （字符串，可选）：设备的ID

• 退货：成功状态
• 示例: skipToNext()

1. “ 跳转到上一个 ”

• 描述：跳到当前播放队列中的上一首曲目
• 参数:

- 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. '添加曲目播放列表'

• 描述：将曲目添加到现有的Spotify播放列表
• 参数:

- playlistId （string）：播放列表的ID - trackUris （array）：要添加的跟踪URI或ID的数组 - position （数字，可选）：插入轨迹的位置

• 退货：成功状态和快照ID
• 示例: addTracksToPlaylist({ playlistId: "3cEYpjA9oz9GiPac4AsH4n", trackUris: ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh"] })

1. 'addToQueue'

• 描述：将曲目、专辑、艺术家或播放列表添加到当前播放队列
• - 参数:

- uri （字符串，可选）：要添加到队列中的项目的Spotify URI（覆盖类型和id） - type （字符串，可选）：要排队的项目类型（曲目、专辑、艺术家、播放列表） - id （字符串，可选）：要排队的项目的Spotify ID - deviceId （string，可选）：要排队的设备的ID

• 退货：成功状态
• 示例: addToQueue({ uri: "spotify:track:6rqhFgbbKwnb9MLmUQDhG6" })
• 替代: addToQueue({ type: "track", id: "6rqhFgbbKwnb9MLmUQDhG6" })

MCP Spotify服务器设置

0.正确安装的要求：

• Node.js v20+最低版本(推荐v22+)
• Spotify 保费账户
• A注册 Spotify开发者应用程序 将用于生成 客户Id 和 clientSecret (https://developer.spotify.com/dashboard)

1.克隆存储库、安装和构建：

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

2.创建Spotify开发者应用程序

1. 转到 Spotify开发者仪表板
2. 使用您的Spotify帐户登录
3. 点击 创建应用程序 按钮
4. 填写 应用程序名称 和 应用程序描述，然后，添加一个 重定向URI （例如。， http://127.0.0.1:8088/callback)&检查 Web播放SDK 和 Web API 复选框。
5. 接受服务条款复选框并单击 保存
6. 在新应用程序的仪表板中，您将看到 客户端ID
7. 点击 显示客户端密码 揭示你的 客户端密钥
8. 如果您想稍后编辑此配置，请单击 编辑设置

3.Spotify API配置

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

# Copy the example config file with this command
cp spotify-config.example.json spotify-config.json

*然后编辑 spotify-config.json 包含您的凭据和重定向URI的文件：*

{
  "clientId": "your-spotify-clientId",
  "clientSecret": "your-spotify-clientSecret",
  "redirectUri": "http://127.0.0.1:8088/callback",
  "accessToken": "execute_npm_run_auth_to_get_accessToken",
  "refreshToken": "execute_npm_run_auth_to_get_resfreshToken"
}

4a。身份验证过程（第一次-获取“accessToken”和“refreshToken”）

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

1. 使用身份验证脚本运行应用程序：

npm run auth

1. 这 npm run auth 脚本将打开浏览器，并转到您需要在浏览器中手动授权的Spotify授权URL。

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

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

1. 身份验证脚本将自动将此代码交换为 accessToken 和 refresToken.

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

{
  "clientId": "your-spotify-clientId",
  "clientSecret": "your-spotify-clientSecret",
  "redirectUri": "http://127.0.0.1:8088/callback",
  "accessToken": "BQCC4lx...pk2",
  "refreshToken": "AQDYbe...jk"
}

*如果在运行时检测到有效的accessToken npm run auth 命令，它不会提示您再次进行身份验证，并使用现有的refreshToken自动刷新accessToken refreshAccessToken 工具。*

4b。身份验证过程（后续时间-使用“refreshToken”工具获取“accessToken”，无需手动用户浏览器确认）

1. 在接下来的处决中 npm run auth，它将自动刷新 accessToken 与现有 refreshToken 使用 refreshAccessToken 工具，服务器将始终自动刷新 accessToken 需要时，使用 refreshAccessToken 工具，只有当 refreshToken 已过期，调用 getAccessToken 获取新工具 accessToken 和 refreshToken，在这种情况下，您需要再次在浏览器中确认身份验证。

“accessToken”终端查看和检查状态

您可以使用查看“accessToken”并检查其状态 sh spotify-check-token.sh 在项目根目录中提示的终端中。

与Claude Desktop、Cursor和VsCode集成 通过“cline”模型扩展

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

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

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

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

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

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

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