AI导哈

Spotify音乐控制协议服务器

一个通过命令行接口访问Spotify的协议服务器，支持搜索曲目/专辑/艺术家、读取播放列表和控制播放（播放/暂停/下一首/上一首）。

  • by youryss
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 youryss/spotify-mcp

使用说明

Spotify MCP（命令行界面服务器）

访问Spotify的模型上下文协议服务器：搜索曲目/专辑/艺术家，阅读播放列表，控制播放（播放/暂停/下一个/上一个）。运行IDE代理的stdio。

设置

1.Spotify开发者设置

首先，您需要创建一个Spotify应用程序来获取您的客户端ID：

  1. 访问Spotify开发者仪表板: https://developer.spotify.com/dashboard
  2. 登录 使用您的Spotify帐户
  3. 创建新应用程序:
    • 点击“创建应用”
    • 填写应用程序名称和描述
    • 将重定向URI设置为： http://127.0.0.1:5173/callback （或使用您的自定义端口）
    • 接受条款并创建应用程序
  4. 复制您的客户ID 从应用程序设置

有关详细说明，请参阅 Spotify Web API入门指南.

2.环境配置

复制 .env.example 创建本地环境配置的文件：

cp .env.example .env

然后编辑 .env 使用您的Spotify凭据：

# .env
SPOTIFY_CLIENT_ID=your_spotify_client_id_here
SPOTIFY_REDIRECT_PORT=5173

重要:

  • 替换 your_spotify_client_id_here 使用您的实际Spotify客户端ID
  • 这 SPOTIFY_REDIRECT_PORT 必须与Spotify应用程序的重定向URI中的端口匹配
  • 永不承诺 .env 到版本控制（它已经在 .gitignore)

3.安装和构建

npm install
npm run build

用法

快速配置示例

以下是Cursor IDE的完整工作示例：

{
  "spotify-mcp": {
    "command": "/Users/yourusername/.nvm/versions/node/v22.11.0/bin/node",
    "args": [
      "--env-file",
      "/Users/yourusername/spotify-mcp/.env",
      "/Users/yourusername/spotify-mcp/dist/index.js"
    ]
  }
}

重要的定制步骤：

  1. 替换 /Users/yourusername 使用您的实际主目录路径
  2. 如果使用nvm，请更新节点版本路径（请与 which node)
  3. 将项目路径更新到克隆的位置 spotify-mcp

要找到您的路径：

# Your node path (if using nvm)
which node

# Your project path
cd /path/to/spotify-mcp
pwd

为什么是这种配置？

  • 用途 --env-file 标记以自动加载您的 .env 文件
  • 无需手动设置环境变量
  • 与nvm管理的Node.js安装可靠地工作

运行服务器

  • 开发模式: npm run dev
  • MCP stdio服务器: npm run mcp

首次运行时，浏览器将打开进行OAuth身份验证。令牌通过服务中的操作系统密钥链安全存储 spotify-mcp.

与Cursor IDE一起使用

  1. 完成上述设置步骤 （Spotify开发者设置、环境配置、安装和构建）

  2. 配置光标 要使用此MCP服务器：

    • 打开光标设置（在macOS上为Cmd+，在Windows/Linux上为Ctrl+）
    • 转到“功能”→ “模型上下文协议”
    • 点击“添加服务器”或直接编辑MCP配置文件(~/.cursor/mcp.json)
    • 使用上述“快速配置示例”部分中的配置
    • 自定义路径以匹配您的系统（请参阅该节中的说明）

    替代方案：简单的npm配置（可能不适用于nvm）

    {
  "spotify-mcp": {
    "command": "npm",
    "args": ["run", "mcp"],
    "cwd": "/absolute/path/to/your/spotify-mcp"
  }
}

  3. 重新启动游标 添加配置后

  4. 验证连接:

    • 在Cursor中打开新聊天
    • 类型：“ping”-您应该从Spotify MCP服务器收到“pong”响应
    • 类型：“获取设备”-应列出您可用的Spotify设备

  5. 首次身份验证:

    • 首次使用时，浏览器窗口将自动打开Spotify OAuth
    • 登录并授权应用程序
    • 您的令牌将安全地存储在系统的密钥链中
    • 授权后，返回Cursor-服务器将准备好使用

  6. 开始使用Spotify工具 在您的Cursor聊天中：

    • “搜索披头士乐队的歌曲”
    • “显示我的播放列表”
    • “播放下一首歌”
    • “现在在玩什么？”
    • “列出我的可用设备”

与Claude Desktop一起使用

  1. 完成上述设置步骤 （Spotify开发者设置、环境配置、安装和构建）

  2. 添加到Claude桌面配置:

    • 找到您的Claude Desktop配置文件：
      • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
      • 窗户： %APPDATA%\Claude\claude_desktop_config.json
      • Linux： ~/.config/Claude/claude_desktop_config.json
    • 编辑配置文件并添加MCP服务器：
    {
  "mcpServers": {
    "spotify-mcp": {
      "command": "/Users/yourusername/.nvm/versions/node/nodeversion/bin/node",
      "args": [
        "--env-file",
        "/Users/yourusername/spotify-mcp/.env",
        "/Users/yourusername/spotify-mcp/dist/index.js"
      ]
    }
  }
}

    重要:

    • 按照“快速配置示例”部分所述自定义路径
    • 使用绝对路径，而不是相对路径
    • 确保 dist 运行时文件夹已存在 npm run build 第一
    • 编辑后保存配置文件

    替代方案：简单的npm配置（可能不适用于nvm）

    {
  "mcpServers": {
    "spotify-mcp": {
      "command": "npm",
      "args": ["run", "mcp"],
      "cwd": "/absolute/path/to/your/spotify-mcp"
    }
  }
}

  3. 重新启动克劳德桌面 完全

  4. 首次身份验证:

    • 首次使用时，浏览器窗口将自动打开Spotify OAuth
    • 登录并授权应用程序
    • 您的令牌将安全地存储在系统的密钥链中

  5. 使用Spotify命令 在您的对话中：

    • 让Claude搜索音乐、控制播放或浏览播放列表
    • 示例：“搜索酷玩乐队的歌曲”，“我的Spotify上正在播放什么？”，“跳到下一首曲目”

快速启动命令

配置后，您可以使用自然语言命令，如：

  • “搜索爵士乐专辑”
  • “播放我喜欢的歌曲播放列表”
  • “跳到下一首曲目”
  • “哪些设备可用于播放？”
  • “显示我的‘Chill’播放列表中的歌曲”

可用工具

MCP服务器提供以下Spotify集成工具：

  • search(type, q, limit?) -搜索曲目、专辑或艺术家
  • get_playlists(limit?, offset?) -获取用户的播放列表
  • get_playlist_items(playlistId, limit?, offset?) -从特定播放列表中获取项目
  • playback_control(action, deviceId?) -控制播放（播放、暂停、下一个、上一个）
  • current_playback() -获取当前播放状态
  • devices() -列出可用的播放设备

故障排除

常见问题

  1. “找不到客户端ID”错误:

    • 确保您的 .env 文件存在并包含 SPOTIFY_CLIENT_ID
    • 验证客户端ID是否正确（从Spotify开发者仪表板复制）

  2. “重定向URI不匹配”错误:

    • 检查一下 SPOTIFY_REDIRECT_PORT 在 .env 匹配您的Spotify应用程序的重定向URI
    • 重定向URI应为 http://127.0.0.1:5173/callback （将5173替换为您的端口）

  3. 身份验证问题:

    • 清除存储的令牌：令牌存储在您的操作系统密钥链中 spotify-mcp
    • 在macOS上：使用Keychain Access应用程序删除 spotify-mcp 条目
    • 尝试再次运行服务器以重新进行身份验证

  4. MCP服务器未连接:

    • 确保服务器成功构建： npm run build
    • 检查一下 cwd MCP配置中的路径正确
    • 验证Node.js和npm是否已安装并且是最新的

获取帮助

相关 MCP