AI导哈

Spotify播放列表构建服务

一个专注于播放列表构建和音乐发现的Spotify MCP服务器，提供19种精细工具，适用于Claude和其他LLM代理。

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

使用说明

mcp spotify

Spotify的MCP服务器，专注于播放列表构建和音乐发现。19个专为与Claude和其他LLM代理一起使用而设计的粒度工具。

先决条件

设置

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

  1. 去 Spotify开发者仪表板
  2. 点击 创建应用程序
  3. 在...之下 您计划使用哪些API/SDK？，选择 Web API
  4. 设置 重定向URI 到 http://127.0.0.1:8888/callback
  5. 注意你的 客户端ID 和 客户端密钥

2.安装

cd mcp-spotify
uv sync

3.配置环境变量

在运行服务器之前设置这些：

export SPOTIFY_CLIENT_ID="your_client_id"
export SPOTIFY_CLIENT_SECRET="your_client_secret"
export SPOTIFY_REDIRECT_URI="http://127.0.0.1:8888/callback"

4.首次运行（身份验证）

uv run mcp-spotify

首次运行时，会打开一个浏览器窗口，用于Spotify OAuth授权。批准后，令牌将缓存在 ~/.spotify_mcp_cache 后续运行会自动进行身份验证。

克劳德桌面/Claude代码配置

添加到您的MCP服务器配置中。如果从PyPI安装：

{
  "mcpServers": {
    "spotify": {
      "command": "uvx",
      "args": ["mcp-spotify"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8888/callback"
      }
    }
  }
}

或者，如果从本地克隆运行：

{
  "mcpServers": {
    "spotify": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-spotify", "run", "mcp-spotify"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8888/callback"
      }
    }
  }
}

工具

发现

工具 参数 说明
search_tracks query, limit=20 寻找足迹。支持 genre:, year:, artist: 过滤器。
search_artists query, limit=20 寻找艺术家。返回名称、流派和ID。
search_albums query, limit=20 搜索相册。返回姓名、艺术家、发布日期和ID。
get_album_tracks album_id, limit=50 列出专辑中的所有曲目。

图书馆

工具 参数 说明
get_saved_tracks limit=20, offset=0 您喜欢/保存的曲目，最近的第一个。

播放列表

工具 参数 说明
create_playlist name, description="", public=True 创建新的播放列表。
add_tracks_to_playlist playlist_id, track_ids 将曲目添加到播放列表（最多100首）。
remove_tracks_from_playlist playlist_id, track_ids 从播放列表中删除曲目。
get_playlist_tracks playlist_id, limit=50, offset=0 在播放列表中列出曲目。
replace_playlist_tracks playlist_id, track_ids 替换播放列表中的所有曲目（用于重新排序）。
follow_playlist playlist_id 关注（保存）播放列表到您的库。
unfollow_playlist playlist_id 从库中取消关注（删除/删除）播放列表。
get_my_playlists limit=50 列出您的播放列表。

个性化

工具 参数 说明
get_my_top_tracks time_range="medium_term", limit=20 您播放次数最多的曲目。
get_my_top_artists time_range="medium_term", limit=20 你最喜欢的艺术家。

time_range 选项： short_term （~4周）， medium_term （~6个月）， long_term （所有时间）。

回放

工具 参数 说明
play_track track_uri 播放曲目（需要活动的Spotify设备）。
pause_playback （无） 暂停播放。
add_to_queue track_uri 将曲目添加到播放队列。
get_now_playing （无） 获取当前曲目信息。

OAuth 授权范围

此服务器请求所需的最小作用域：

  • user-read-playback-state, user-modify-playback-state, user-read-currently-playing --回放
  • playlist-read-private, playlist-read-collaborative, playlist-modify-public, playlist-modify-private --播放列表
  • user-top-read --个性化
  • user-library-read --已保存/喜欢的曲目

Spotify Web API限制

自2024年末以来，Spotify已逐步锁定其Web API。本节记录了受影响的内容及其对该项目的意义。

从Web API中删除（2024年11月）

Spotify于2024年11月27日删除或限制了这些端点。他们是 永久不可用 新应用程序和开发模式应用程序，无论配额如何：

终点 它做了什么 影响
GET /recommendations 基于种子曲目/艺术家/流派的算法曲目推荐 是构建播放列表的最佳工具。API中不存在替换项。
GET /audio-features 曲目的节奏、能量、可跳舞性、效价等 无法按音乐属性过滤或排序曲目。
GET /audio-analysis 详细的音频结构（节拍、小节、小节、音色） 无法分析曲目结构。
GET /browse/featured-playlists Spotify的编辑/算法播放列表 无法浏览策划的播放列表。
GET /browse/categories/{id}/playlists 浏览类别中的播放列表 无法按类别发现播放列表。
轨道 preview_url 字段 30秒音频预览URL 预览URL现在返回 null 适用于非祖父级应用程序。

具有扩展配额模式批准的应用程序 之前 2024年11月保留了访问权限。新应用程序无法访问这些端点。

限制扩展配额（实际上无法访问）

这些端点存在，但返回 403禁止 发展模式。他们需要扩展配额模式，截至2025年5月，该模式要求：

  • 合法注册的商业实体（非个人）
  • 250000+月活跃用户
  • 在主要Spotify市场推出的活跃服务

这使得扩展配额 个人项目、爱好应用程序和小工具无法访问.

端点 它做了什么
GET /artists/{id}/related-artists 发现类似的艺术家。返回403。
GET /artists/{id}/top-tracks 获取艺术家最受欢迎的曲目。返回403。

2026年2月开发模式变更

2026年2月6日，Spotify彻底改革了开发模式本身：

  • 需要Spotify Premium 对于应用程序所有者（这现在是所有Web API访问的先决条件）
  • 每个开发人员1个客户端ID
  • 最多5个授权用户 每个应用程序
  • 搜索结果上限为10 新应用程序的每个请求（从50个减少到50个）
  • 多个端点受到限制（批量获取端点、浏览类别、新版本、其他用户配置文件/播放列表）

这 POST /users/{user_id}/playlists 终点也被删除，以支持 POST /me/playlists （此服务器已使用 /me 变体）。

注： 端点限制当前适用于 新建 应用程序。在社区强烈反对后，现有的Dev Mode应用程序被暂时豁免，但这可能会改变。

尚未实施

可以在当前开发模式访问中添加的潜在工具：

工具 端点 描述
skip_to_next POST /me/player/next 跳到队列中的下一首曲目。
skip_to_previous POST /me/player/previous 跳至上一曲目。
get_queue GET /me/player/queue 查看当前播放队列。
set_volume PUT /me/player/volume 设置播放音量（仅限高级版）。
set_repeat PUT /me/player/repeat 设置重复模式（跟踪/上下文/关闭）。
set_shuffle PUT /me/player/shuffle 打开/关闭随机播放
get_devices GET /me/player/devices 列出可用的播放设备。
transfer_playback PUT /me/player 将播放转移到其他设备。
save_tracks PUT /me/tracks 将曲目保存到用户的库中。

永远不会可用（适用于新应用程序）

这些对这个项目来说很有价值，但永远遥不可及：

功能 为什么重要 状态
算法推荐 以编程方式发现新音乐的最佳方式 2024年11月删除，无替代品
音频功能（节奏、能量等） 允许按情绪、能量、舞蹈性过滤曲目 2024年11月删除
相关艺术家 “如果你喜欢X，试试Y”工作流的核心发现工具 需要扩展配额（25万MAU）
艺术家热门曲目 快速采样艺术家最受欢迎作品的方法 需要扩展配额（25万MAU）
编辑/分类播放列表 按流派或情绪发现Spotify策划的播放列表 2024年11月删除

实际效果：播放列表的构建完全依赖于 search_tracks 以及用户自己的收听历史(get_my_top_tracks, get_my_top_artists)为了发现。克劳德自己的音乐知识填补了API不再提供的空白。

发展

uv run mcp-spotify           # Run the server
uv run pytest tests/ -v      # Run tests
uv run ruff check src/       # Lint
uv run ruff format src/      # Format
uv run pyright src/          # Type check

预提交钩子

此项目使用 左钩 用于预提交检查。安装时使用 brew install lefthook （或参见 其他安装方法)那么：

lefthook install

相关 MCP