AI导哈

Spotify音乐控制协议

一个通过Claude进行自然语言交互控制Spotify播放、搜索音乐和管理播放列表的模型上下文协议服务器。

  • by verIdyia
  • Python
  • 本地部署
  • 8 星标
  • 更新于
在 GitHub 查看 verIdyia/spotify-mcp

使用说明

spotify mcp

A. 模型上下文协议（MCP） 连接克劳德和Spotify的服务器。通过与Claude的自然对话，控制您的Spotify播放、搜索音乐、管理播放列表等。

分叉通知：此项目是从 varunnal/spotify mcp 并更新为 Spotify Web API 2026年2月更改.建造和维护 克劳德代码.

更改内容（v0.4.0）

架构重写

  • 掉落 spotipy --用途 httpx 直接异步（本机异步，否 asyncio.to_thread 包装）
  • 单个模块 -- server.py, spotify_api.py, utils.py 合并到一个文件中
  • FastMCP --清洁 @mcp.tool() 装饰器，而不是手动ToolModel+匹配/案例路由
  • 2依赖关系 --只有 mcp + httpx （是 mcp + spotipy + python-dotenv)
  • 显式OAuth -- spotify-mcp --auth 对于初始设置，后续使用时自动刷新

功能（从v0.3.0开始保留）

  • 开始、暂停和跳过播放
  • 搜索曲目、专辑、艺术家和播放列表
  • 获取有关任何Spotify项目的详细信息
  • 管理播放队列
  • 完整播放列表CRUD（创建、读取、更新、删除曲目）
  • 使用可选的流派丰富功能检索喜欢/保存的歌曲
  • 适用于Spotify 2026年2月API更改

运作原理

Claude <--MCP (stdio)--> spotify-mcp <--httpx async--> Spotify Web API
  1. Claude通过MCP协议发送工具调用
  2. 服务器使用将它们转换为Spotify Web API请求 httpx
  3. OAuth令牌自动刷新；初始身份验证 spotify-mcp --auth
  4. 结果被解析为简洁的JSON并返回给Claude

可用工具

工具 操作 描述
spotify_playback get, start, pause, skip, previous, volume 控制音乐播放和音量
spotify_search -- 搜索曲目、专辑、艺术家、播放列表
spotify_queue get, add 查看和管理播放队列
spotify_get_info -- 通过Spotify URI获取详细项目信息
spotify_playlist get, get_tracks, add_tracks, remove_tracks, change_details, create, delete 完整播放列表管理
spotify_liked_songs get, get_with_genres, like, unlike, check 管理已保存的歌曲并检查曲库
spotify_recently_played -- 获取最近播放的带有时间戳的曲目
spotify_devices list, transfer 列出设备并传输回放

建筑

src/spotify_mcp/
  __init__.py   # Entry point (stdio / --auth)
  server.py     # FastMCP server, API client, parsers — all in one

先决条件

  • Python 3.12+
  • Spotify高级 帐户（自2026年2月起，开发模式API访问需要）
  • Spotify开发者应用 凭证

配置

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

  1. 首选 developer.spotify.com/dashboard
  2. 创建新应用程序
  3. 将重定向URI设置为 http://127.0.0.1:8080/callback
  4. 注意你的 客户端ID 和 客户端密钥

重要（2026年2月）：开发模式应用程序仅限于5名授权用户，并要求应用程序所有者拥有Spotify Premium。

2.初始身份验证

运行一次auth流以获取OAuth令牌：

SPOTIFY_CLIENT_ID=your_id SPOTIFY_CLIENT_SECRET=your_secret uv run spotify-mcp --auth

这将打开一个用于Spotify登录的浏览器，然后将令牌保存到 ~/.spotify_mcp_cache.json.

3.添加到MCP客户端

本地运行（推荐）

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

添加到您的MCP配置中（Claude Desktop、Cursor等）：

{
  "mcpServers": {
    "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"
      }
    }
  }
}

用uvx跑步

{
  "mcpServers": {
    "spotify": {
      "command": "uvx",
      "args": [
        "--python", "3.12",
        "--from", "git+https://github.com/verIdyia/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"
      }
    }
  }
}

环境变量

变量 必填 默认 描述
SPOTIFY_CLIENT_ID 是 -- Spotify应用程序客户端ID
SPOTIFY_CLIENT_SECRET 是 -- Spotify应用程序客户端密码
SPOTIFY_REDIRECT_URI 没有 http://127.0.0.1:8080/callback OAuth重定向URI
SPOTIFY_CACHE_PATH 没有 ~/.spotify_mcp_cache.json 令牌缓存文件路径

故障排除

  1. 首次运行：运行 spotify-mcp --auth 在与MCP客户端一起使用之前完成OAuth流程
  2. 令牌已过期：令牌自动刷新。如果问题仍然存在，请重新运行 --auth
  3. 无活动设备：确保Spotify已打开，并在至少一台设备上播放
  4. 确保 uv 已更新 --版本 >=0.54 推荐

调试

启动MCP检查器：

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

Spotify API 2026年2月变更摘要

更改 影响 状态
搜索 limit 最多减少50个->10个 每次搜索的结果更少 已调整
播放列表端点 /tracks -> /items 端点URL已更改 已调整
响应字段 tracks -> items 解析已更新 已调整
批处理GET端点已删除 必须单独获取 已调整
popularity 已从曲目中删除字段 不再可用 已处理
开发模式：5个用户限制，需要高级 访问限制 记录

学分

许可证

MIT许可证——见 许可证 了解详情。

相关 MCP