spotify-mcp MCP 服务器

MCP 项目用于将 Claude 与 Spotify 连接起来。基于 spotipy-dev 的 API 构建。

[2026年3月公告]：该项目已停止维护。大多数拉取请求将不会被合并。

功能

• 开始、暂停和跳过播放
• 搜索曲目、专辑、艺术家和播放列表
• 获取曲目、专辑、艺术家和播放列表的信息
• 管理 Spotify 队列
• 管理、创建和更新播放列表

演示

视频 -- 请打开音频

https://github.com/user-attachments/assets/20ee1f92-f3e3-4dfa-b945-ca57bc1e0894

配置

获取 Spotify API 密钥

在 developer.spotify.com 上创建一个账户。导航到 控制台。 创建一个应用，将 redirect_uri 设置为 http://127.0.0.1:8080/callback。 您可以选择任何端口，但必须使用 http 协议和明确的回环地址（IPv4 或 IPv6）。

更多信息和故障排除，请参阅 此处。 您可能需要重启一次或两次您的 MCP 环境（例如 Claude Desktop），才能使其正常工作。

找到 MCP 配置文件

对于 Cursor、Claude Desktop 或任何其他支持 MCP 的客户端，您都需要找到您的配置文件。

• 在 macOS 上，Claude Desktop 的配置文件位置为：~/Library/Application\ Support/Claude/claude_desktop_config.json
• 在 Windows 上，Claude Desktop 的配置文件位置为：%APPDATA%/Claude/claude_desktop_config.json

使用 uvx 运行该项目

将以下代码片段添加到您的 MCP 配置中。

{
  "mcpServers": {
    "spotify": {
      "command": "uvx",
      "args": [
        "--python", "3.12",
        "--from", "git+https://github.com/varunneal/spotify-mcp",
        "spotify-mcp"
      ],
      "env": {
        "SPOTIFY_CLIENT_ID": YOUR_CLIENT_ID,
        "SPOTIFY_CLIENT_SECRET": YOUR_CLIENT_SECRET,
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8080/callback"
      }
    }
  }
}

在本地运行该项目

使用 UVX 会在每次调用工具时打开 Spotify 的重定向 URI。为了避免这种情况，您可以克隆此仓库并在本地运行：

git clone https://github.com/varunneal/spotify-mcp.git

然后将其添加到您的 MCP 配置中，如下所示：

"spotify": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/spotify-mcp",
      "run",
      "spotify-mcp"
    ],
    "env": {
      "SPOTIFY_CLIENT_ID": YOUR_CLIENT_ID,
      "SPOTIFY_CLIENT_SECRET": YOUR_CLIENT_SECRET,
      "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8080/callback"
    }
  }

故障排除

如果您无法使此 MCP 正常工作，请提交一个问题。以下是一些提示：

1. 确保 uv 已更新。建议使用 >=0.54 版本。
2. 如果是本地克隆，请为项目启用执行权限：chmod -R 755。
3. 确保您拥有 Spotify Premium 账户（运行开发者 API 所需）。

此 MCP 将按照 MCP 规范将日志输出到标准错误流。在 Mac 上，Claude Desktop 应该会将这些日志输出到 ~/Library/Logs/Claude。 在其他平台上，您可以在这里找到日志。

您可以通过 npm 使用以下命令启动 MCP 检查器：

npx @modelcontextprotocol/inspector uv --directory /path/to/spotify-mcp run spotify-mcp

启动后，检查器会显示一个 URL，您可以在浏览器中访问该 URL 来开始调试。

待办事项

不幸的是，Spotify API 中的一些很酷的功能已经被 弃用。大多数新功能都相对较小，或者是为了项目的健康而进行的改进：

• 测试。
• 增加对管理播放列表的 API 支持。
• 增加对分页搜索结果、播放列表和专辑的 API 支持。

欢迎贡献 PR！感谢 @jamiew、@davidpadbury、@manncodes、@hyuma7、@aanurraj、@JJGO 等人的贡献。

spotify-mcp 快速上手指南

spotify-mcp 是一个 MCP 服务器，旨在将 Claude 与 Spotify 连接，让你可以通过自然语言控制音乐播放、搜索曲目及管理播放列表。

注意：该项目目前处于非活跃维护状态（截至 2026 年 3 月），大部分新功能请求可能不会被合并，但核心功能仍可使用。

环境准备

在开始之前，请确保满足以下条件：

1. Spotify 账号：必须拥有 Spotify Premium 订阅（开发者 API 限制）。
2. 系统要求：macOS 或 Windows。
3. 前置依赖：
   • 安装 uv (推荐版本 >=0.54)。
   • 安装支持 MCP 的客户端（如 Claude Desktop 或 Cursor）。
4. 获取 API 密钥：
   • 访问 Spotify Developer Dashboard 登录并创建应用。
   • 设置 Redirect URI 为 http://127.0.0.1:8080/callback（端口可自定义，但必须是 http 和本地回环地址）。
   • 记录生成的 Client ID 和 Client Secret。

安装步骤

你需要将配置添加到 MCP 客户端的配置文件中。

1. 定位配置文件

根据你的操作系统和客户端，找到配置文件路径：

• macOS (Claude Desktop): ~/Library/Application\ Support/Claude/claude_desktop_config.json
• Windows (Claude Desktop): %APPDATA%/Claude/claude_desktop_config.json
• Cursor: 通常在设置中通过 "MCP Servers" 界面管理，或直接编辑对应的 JSON 配置。

2. 配置服务器

推荐使用 uvx 方式运行，无需克隆代码即可直接使用。将以下片段添加到配置文件的 mcpServers 对象中，并替换你的密钥：

{
  "mcpServers": {
    "spotify": {
      "command": "uvx",
      "args": [
        "--python", "3.12",
        "--from", "git+https://github.com/varunneal/spotify-mcp",
        "spotify-mcp"
      ],
      "env": {
        "SPOTIFY_CLIENT_ID": "你的_CLIENT_ID",
        "SPOTIFY_CLIENT_SECRET": "你的_CLIENT_SECRET",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8080/callback"
      }
    }
  }
}

提示：保存配置后，可能需要重启一次或两次 MCP 客户端（如 Claude Desktop）以使更改生效。首次运行时，浏览器会弹出 Spotify 授权页面，请点击同意以完成连接。

(可选) 本地运行模式：如果你希望避免每次调用工具都打开重定向 URI，可以克隆仓库并在本地运行：

git clone https://github.com/varunneal/spotify-mcp.git
chmod -R 755 spotify-mcp  # macOS/Linux 需要执行此步赋予权限

然后将配置中的 command 改为 uv，args 调整为指向本地路径：

"command": "uv",
"args": [
  "--directory",
  "/path/to/spotify-mcp",
  "run",
  "spotify-mcp"
]

基本使用

配置成功并重启客户端后，你可以在对话框中直接使用自然语言指令控制 Spotify。

使用示例：

• 播放控制：

  "帮我播放周杰伦的《七里香》。" "暂停当前播放。" "跳过这首歌。"

• 搜索与信息：

  "搜索一下 Taylor Swift 的最新专辑。" "告诉我当前正在播放的歌曲信息。"

• 播放列表管理：

  "创建一个名为'工作专注'的新播放列表。" "把当前歌曲添加到我的'喜欢的音乐'列表中。" "显示我的播放队列。"

只需像与人交谈一样发出指令，AI 将自动调用 Spotify API 执行相应操作。