Spotify MCP 服务器

PyPI

一个 Model Context Protocol (MCP) 服务器，提供与 Spotify Web API 交互的工具。使 Claude 等 AI 助手能够搜索音乐、控制播放、管理播放列表等。

功能

搜索 - 查找曲目、专辑、艺术家、播放列表、节目、剧集和有声读物
播放控制 - 播放、暂停、跳过、定位、音量、随机播放、重复播放、队列管理
播放列表 - 创建、更新、添加/移除/重新排序曲目
资料库 - 查看和管理已保存的曲目、专辑、节目、剧集和有声读物
浏览 - 获取专辑详情、艺术家信息、曲目元数据
播客与有声读物 - 浏览节目、剧集、有声读物和章节
用户个人资料 - 查看个人资料、热门艺术家/曲目、关注的艺术家
44 个工具 涵盖了非弃用的 Spotify Web API 端点

先决条件

uv — 使用 curl -LsSf https://astral.sh/uv/install.sh | sh 安装
一个 Spotify 开发者账户
一个拥有 Client ID 和 Client Secret 的 Spotify 应用

获取您的 Spotify 凭据

前往 Spotify 开发者仪表板
点击 Create App
填写应用详情：
- App name: 选择任意名称（例如 "My MCP Server"）
- App description: 可选
- Redirect URI: http://127.0.0.1:8888/callback
- Which API/SDKs are you planning to use?: 选择 Web API
点击 Save
在您的应用页面上，找到您的 Client ID
点击 Show client secret 以显示您的 Client Secret

重要提示：重定向 URI 必须完全匹配 http://127.0.0.1:8888/callback（或您在 SPOTIFY_REDIRECT_URI 中设置的任何内容）。不要使用 localhost — 请使用 127.0.0.1。

安装

在下方选择您的客户端。所有示例均使用 uvx 按需获取服务器 — 无需克隆，无需手动安装。

Claude Code

claude mcp add spotify \
  -e SPOTIFY_CLIENT_ID=your_client_id \
  -e SPOTIFY_CLIENT_SECRET=your_client_secret \
  -- uvx mcp-server-spotify

其他 MCP 客户端

大多数 MCP 客户端通过 JSON 文件配置服务器。将此条目添加到您的客户端 MCP 配置中：

{
  "mcpServers": {
    "spotify": {
      "command": "uvx",
      "args": ["mcp-server-spotify"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

从本地检出运行

对于开发，或者如果您想运行修改后的副本：

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

然后将您的客户端指向本地检出目录，而不是 uvx：

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

配置

变量	必需	默认值	描述
`SPOTIFY_CLIENT_ID`	是	—	您的 Spotify 应用的 Client ID
`SPOTIFY_CLIENT_SECRET`	是	—	您的 Spotify 应用的 Client Secret
`SPOTIFY_REDIRECT_URI`	否	`http://127.0.0.1:8888/callback`	OAuth 重定向 URI

身份验证

服务器使用 Spotify 的 授权码 (Authorization Code) 流程：

首次使用时，服务器会在您的浏览器中打开 Spotify 登录页面
Spotify 将要求您批准访问 — 服务器会请求完整工具集所需的所有范围（播放、资料库、播放列表和用户数据）
授权后，Spotify 会重定向到本地回调服务器
服务器将授权码交换为访问/刷新令牌
令牌安全地存储在 ~/.spotify-mcp/credentials.json 中
令牌在过期时会自动刷新

如果在无头环境（SSH、Docker）中运行，授权 URL 将打印到 stderr — 请手动将其复制并粘贴到浏览器中。

重新身份验证

要重新身份验证（例如在撤销访问权限后），请删除存储的凭据：

rm ~/.spotify-mcp/credentials.json

可用工具

搜索

工具	描述
`search`	搜索曲目、专辑、艺术家、播放列表、节目、剧集或有声读物

专辑

工具	描述
`get_album`	通过 ID 获取专辑详情
`get_album_tracks`	获取专辑中的曲目

艺术家

工具	描述
`get_artist`	通过 ID 获取艺术家详情
`get_artist_albums`	获取艺术家的专辑

曲目

工具	描述
`get_track`	通过 ID 获取曲目详情

播放列表

工具	描述
`get_playlist`	获取播放列表详情
`update_playlist`	更新播放列表名称、描述或可见性
`get_playlist_items`	获取播放列表中的项目
`add_playlist_items`	向播放列表添加曲目/剧集
`remove_playlist_items`	从播放列表中移除项目
`reorder_playlist_items`	重新排序播放列表中的项目
`get_my_playlists`	获取当前用户的播放列表
`create_playlist`	创建新播放列表

资料库

工具	描述
`get_saved_tracks`	获取已保存的曲目
`get_saved_albums`	获取已保存的专辑
`get_saved_shows`	获取已保存的节目
`get_saved_episodes`	获取已保存的剧集
`get_saved_audiobooks`	获取已保存的有声读物
`save_to_library`	将项目保存到资料库
`remove_from_library`	从资料库中移除项目
`check_saved_in_library`	检查项目是否在资料库中

播放器

工具	描述
`get_playback_state`	获取当前播放状态
`get_currently_playing`	获取当前正在播放的曲目
`play`	开始或恢复播放
`pause`	暂停播放
`next_track`	跳到下一首曲目
`previous_track`	跳到上一首曲目
`seek`	定位到曲目中的位置
`set_repeat`	设置重复模式 (track/context/off)
`set_volume`	设置播放音量
`toggle_shuffle`	切换随机播放模式
`transfer_playback`	将播放转移到其他设备
`get_devices`	获取可用设备
`add_to_queue`	将项目添加到播放队列
`get_queue`	获取播放队列
`get_recently_played`	获取最近播放的曲目

节目与播客

工具	描述
`get_show`	获取节目详情
`get_show_episodes`	获取节目的剧集

有声读物

工具	描述
`get_audiobook`	获取有声读物详情
`get_audiobook_chapters`	获取有声读物的章节
`get_chapter`	获取章节详情

用户

工具	描述
`get_my_profile`	获取当前用户的个人资料
`get_my_top_items`	获取热门艺术家或曲目

关注艺术家/用户使用相同的 save_to_library / remove_from_library / check_saved_in_library 工具 — 传入艺术家或用户 URI。

贡献

请参阅 CONTRIBUTING.md 了解开发设置和指南。

许可证

MIT - 详情请参阅 LICENSE。

mcp-server-spotify