Spotify

spotify-mcp

mcp-name: io.github.jamiew/spotify-mcp

一个本地 Python MCP 服务，可通过 MCP 客户端搜索 Spotify、控制播放，以及管理播放列表和「已赞歌曲」。它使用你的 Spotify 帐户通过 stdio 运行。 这是 varunneal/spotify-mcp 的受支持分支。

TypeScript 版本支持本地和托管使用，且提供不同的 MCP 接口。

设置

需要 Python 3.12+、uv 和用于播放的 Spotify Premium。

1. 在 Spotify 开发者控制面板中创建应用。
2. 将 http://127.0.0.1:8888 注册为其重定向 URI，必须完全按此填写。
3. 将应用的 Client ID 和 Client Secret 复制到 MCP 客户端的配置中：

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

重启客户端。首次使用时，浏览器会打开 Spotify 授权页面；令牌会缓存在本地。请妥善保管客户端密钥和令牌缓存。播放需要有可用的 Spotify Connect 设备，因此请在要控制的设备上打开 Spotify。

各客户端的设置说明：Claude Desktop、 Claude Code 和 Codex。请按各客户端的格式使用相同的命令和环境变量。

从源代码运行

上面的包命令使用已发布的包，其内容可能落后于本 README 的源代码更改。若要运行当前检出版本：

git clone https://github.com/jamiew/spotify-mcp.git
cd spotify-mcp
uv sync

在上面的配置中，将 command 改为 uv，并将 args 改为 ["--directory", "/absolute/path/to/spotify-mcp", "run", "spotify-mcp"]。 保留相同的环境变量。无需克隆即可使用 uvx --from git+https://github.com/jamiew/spotify-mcp.git spotify-mcp。

**重新授权：**艺术家关注状态检查需要 user-follow-read。现有授权不会自动获得新增的作用域。收到提示时，请重启并完成 Spotify 授权；如果访问仍被拒绝，请检查 Spotify 帐户中该应用的授权，并重新授权。 请勿自动删除身份验证缓存。

功能

28 个工具、六个资源（用户、播放状态、曲目、播放列表、艺术家、专辑）和五个提示词。 工具提供类型化输出和行为注释；读取大型播放列表时会报告进度。 在支持的情况下，移除播放列表内容前会请求确认；重新排序时会使用快照保护； 播放控制会尽力在写入后读取以确认结果，但无法保证成功。

工具

工具	功能
get_me	读取你的个人资料
search_music	按筛选条件和分页搜索曲目、专辑、艺人或播放列表
get_tracks	读取最多 50 首曲目；无法批量读取时逐首读取
get_artist	读取最多 50 位艺人；读取单位艺人的热门曲目
get_album	读取最多 20 张专辑；读取单张专辑的曲目列表
get_playback_state	读取当前曲目、设备、进度、随机播放和循环播放状态
control_playback	播放、暂停、跳过、定位、调节音量，以及控制随机播放和循环播放
list_devices	列出 Spotify Connect 设备
transfer_playback	将播放切换到另一台设备
get_queue	读取正在播放和即将播放的曲目
add_to_queue	将曲目加入队列
list_playlists	分页列出你的播放列表
get_playlist	读取播放列表元数据，不包括曲目
get_playlist_tracks	分页读取播放列表曲目
create_playlist	创建私人播放列表；设置 public=true 即可公开
update_playlist_details	更改名称、描述或可见性
add_tracks_to_playlist	添加最多 100 首曲目
remove_tracks_from_playlist	移除曲目；在支持的情况下进行确认
reorder_playlist	移动一组曲目
unfollow_playlist	取消关注播放列表，包括你自己的播放列表
get_saved_tracks	分页读取「已点赞的歌曲」
save_tracks	点赞曲目
remove_saved_tracks	取消点赞曲目
check_saved_tracks	检查最多 50 首曲目是否在「已点赞的歌曲」中
check_saved_albums	检查最多 20 张已保存的专辑
check_following_artists	检查最多 50 位已关注的艺人
get_top_items	读取某个时间范围内的热门艺人或曲目
get_recently_played	读取最近播放的曲目及其时间戳

须知行为

• 新建播放列表默认为私人。 现有播放列表不会受到影响。Spotify 可能会报告意外的可见性，因此请在 Spotify 应用中确认敏感播放列表的可见性。
• 保存或移除曲目，以及检查曲目或艺人的关注状态时，最多接受 50 项，并以 40 项为一批发送给上游。专辑检查最多接受 20 项。检查结果与输入顺序保持一致；未完成的批次会失败。分批写入并非原子操作：发生错误后，先前的更改可能仍会保留。重试前请先检查状态。
• 受限应用的搜索页面最多为 10。请根据返回的 offset + limit 翻页，而非按请求的数量计算。逐首读取的备用方案最多会发出 50 次 Spotify 请求。
• 播放列表分页会统计各个位置，包括无法解析的条目和 id: null 的本地文件。本地文件也会设置 is_local；这些位置仍可用于重新排序。

Spotify 访问权限与政策

• 权限和应用访问模式决定可用的端点和播放列表访问权限。 403 可能表示缺少权限，而非端点已弃用。现有集成的 2 月限制已推迟； 受限应用使用 2026 年 2 月 API 路由。
• 开发模式 通常允许 5 位加入许可名单的用户，并要求应用所有者拥有 Premium；较早获批的较大许可名单可能保留原有资格。扩展访问权限并非普通爱好项目都能获批： 条件包括组织、法人实体、已上线的服务，以及每月 250,000 名活跃用户。公开 URL 不会取消这些限制。
• 开发者账户中的所有开发模式应用共用一个配额，即使拥有 允许的 25 个 Client IDs 也是如此。 此服务会直接返回 429 错误，不会重试，包括 QUOTA_EXCEEDED，以及在提供 Retry-After 时附带该值的普通速率限制错误。未指定有保证的配额重置时间。
• 此服务使用一个本地身份。请勿共享其令牌缓存，也不要将其作为无需身份验证的公共服务公开。其他用户应自行托管并授权自己的账户。
• AI 政策是另一项独立限制。 Spotify 开发者政策 第 III.14 条限制将 Spotify 内容用于训练 AI/ML 模型或以其他方式将其纳入此类模型； “不训练”或“仅使用元数据”并不代表自动获准。第 III.13 条限制分析和衍生指标；第 III.3 条限制语音控制助手。在向公众开放 AI 访问之前，请先向 Spotify 征求说明或批准。这是风险提示，不构成法律建议或许可。

在不同实现之间切换

版本和工具名称相同，并不意味着与其他实现可直接互换。切换前，请检查参数、限制和结果格式。若工作流依赖此服务的资源、五个提示词、快照保护机制、移除确认或播放确认，请保留这些行为；它们并非所有实现都具备。

致谢

MIT 许可证，版权归 Varun Neal Srivastava 所有，2025 年。 感谢 @varunneal 创建原始项目， 以及 @jamiew、@jonico、 @tedeuxx 和 @karimStekelenburg。

横幅由 Glif 制作。