使用说明

Spotify MCP服务器

一种模型上下文协议（MCP）服务器，使用Spotipy将Spotify控件和查询作为MCP工具公开。

已准备好通过Docker使用 -无需本地安装Python！

快速入门（3个步骤）

1.获取Spotify API证书

首选 Spotify开发者仪表板
创建应用程序（或使用现有应用程序）
注意你的 客户端ID 和 客户端密钥
添加 http://127.0.0.1:8888/callback 到 重定向URI 应用内设置
如果您的应用程序处于“开发模式”，请将您的Spotify帐户电子邮件添加到 用户管理 部分

2.一次性身份验证（Docker）

运行此命令进行身份验证（替换为您的凭据）：

docker run --rm -it \
  -v ${HOME}/.cache/spotify-mcp:/app/.cache \
  -e SPOTIPY_CLIENT_ID=your-client-id \
  -e SPOTIPY_CLIENT_SECRET=your-client-secret \
  -e SPOTIPY_REDIRECT_URI=http://127.0.0.1:8888/callback \
  -e SPOTIPY_CACHE_PATH=/app/.cache/token \
  docker.io/allesy/spotify-mcp:latest python -u -m spotify_mcp.cli.auth_init

打开浏览器中显示的URL
授权应用程序
从浏览器复制完整的重定向URL并将其粘贴回终端
完成！令牌已保存。

3.添加到您的MCP客户端

将此添加到您的MCP客户端配置中（例如。， ~/.cursor/mcp.json 对于Cursor或Claude Desktop的配置）：

{
  "mcpServers": {
    "spotify": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/Users/YOUR_USERNAME/.cache/spotify-mcp:/app/.cache",
        "-e", "SPOTIPY_CLIENT_ID",
        "-e", "SPOTIPY_CLIENT_SECRET",
        "-e", "SPOTIPY_REDIRECT_URI",
        "-e", "SPOTIPY_CACHE_PATH",
        "docker.io/allesy/spotify-mcp:latest"
      ],
      "env": {
        "SPOTIPY_CLIENT_ID": "your-client-id",
        "SPOTIPY_CLIENT_SECRET": "your-client-secret",
        "SPOTIPY_REDIRECT_URI": "http://127.0.0.1:8888/callback",
        "SPOTIPY_CACHE_PATH": "/app/.cache/token"
      }
    }
  }
}

重要：替换 /Users/YOUR_USERNAME 使用您的实际主目录路径（某些MCP客户端无法扩展 ${HOME}).

就是这样！重新启动MCP客户端并开始控制Spotify！ 🎵

功能（工具）

播放和库

搜索：搜索曲目、专辑、艺术家或播放列表
播放/暂停/下一条轨迹/上一条轨迹：控制播放
当前铺设：现在打弦乐，变得友好起来
play_song：按名称搜索并播放第一个结果
play_by_id：按Spotify ID/URI播放曲目或播放列表
list_playlists：列出用户播放列表
list_liked：列出喜欢的歌曲
list_playlist_songs：按ID列出播放列表中的歌曲
add_to_oliked：将曲目添加到喜欢的歌曲
add_to_playlist：将曲目添加到播放列表
喜欢_总计：喜欢歌曲中的曲目数
add_to_queue：将曲目添加到播放队列
get_queue：查看当前队列
get_recently_played：查看收听历史记录
get_top_tracks/get_top_arts：查看您播放次数最多的曲目和艺术家
列表_设备：列出可用的Spotify设备
transfer_playback：将播放移动到其他设备
set_shuffle/set_repeat：控制播放模式
seek_position/set_volume：微调播放

先决条件

码头工人 安装在您的系统上
Spotify开发者应用 （免费）-创建一个 Spotify开发者仪表板
- 客户端ID和客户端密码
- 重定向URI: http://127.0.0.1:8888/callback 已添加到应用程序设置中
- 您的Spotify电子邮件已添加到用户管理中（如果处于开发模式）

从注册表中拉取（无本地构建）

如果您正在使用已发布的图像，请直接将其拉取：

docker pull docker.io/allesy/spotify-mcp:latest

然后按照下面的首次OAuth部分和MCP客户端配置示例进行操作，这两个部分都引用了注册表映像。

运输方式

此服务器支持两种MCP传输：

模式	用例	如何激活
`stdio`	Cursor、Claude Desktop、启动MCP进程的任何客户端	默认值（不需要环境变量）
`sse`	Docker Compose sidecar、远程MCP客户端（如Hermes）	`MCP_TRANSPORT=sse`

Docker镜像始终默认为 stdio 因此，现有的MCP客户端配置保持不变。

SSE模式环境变量

变量	默认值	描述
`MCP_TRANSPORT`	`stdio`	设置为 `sse` 启用HTTP/SSE模式
`MCP_HOST`	`0.0.0.0`	绑定主机
`MCP_PORT`	`8000`	绑定端口
`MCP_SSE_PATH`	`/sse`	SSE端点路径

以SSE服务器（Docker）运行

docker run --rm \
  -p 8000:8000 \
  -v ${HOME}/.cache/spotify-mcp:/app/.cache \
  -e MCP_TRANSPORT=sse \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8000 \
  -e MCP_SSE_PATH=/sse \
  -e SPOTIPY_CLIENT_ID=your-client-id \
  -e SPOTIPY_CLIENT_SECRET=your-client-secret \
  -e SPOTIPY_REDIRECT_URI=http://127.0.0.1:8888/callback \
  -e SPOTIPY_CACHE_PATH=/app/.cache/token \
  docker.io/allesy/spotify-mcp:latest

Docker Compose（独立版）

复制 .env.example 到 .env，填写您的凭据，然后：

docker compose -f docker-compose.spotify-mcp.yml --env-file .env up

Docker与Hermes合作

看 examples/hermes/docker-compose.yml 获取完整的Hermes+Spotify MCP Compose堆栈。

将此添加到您的Hermes配置中(~/.hermes/config.yaml):

mcp_servers:
  spotify:
    url: "http://spotify-mcp:8000/sse"

然后运行：

docker compose -f examples/hermes/docker-compose.yml up

环境变量

通过MCP客户端配置提供这些（不要硬编码）。这些名称符合Spotipy惯例，也是服务器所期望的。

必修的：

SPOTIPY_CLIENT_ID
SPOTIPY_CLIENT_SECRET
SPOTIPY_REDIRECT_URI

可选：

SPOTIFY_SCOPE：覆盖默认OAuth作用域（空格分隔作用域）。默认为启用播放和库/播放列表操作的广泛设置。
SPOTIPY_CACHE_PATH：令牌缓存文件路径（容器内）。当您想要控制确切的缓存位置时很有用。运行Docker时，结合绑定挂载来持久化缓存。

构建

docker build -t spotify-mcp:latest .

与MCP客户端（Docker/stdio）一起使用

示例MCP客户端配置（JSON），通过Docker运行服务器并传递env变量。为您的客户端调整路径（Claude Desktop、Cursor等）。

{
  "mcpServers": {
    "spotify-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "${HOME}/.cache/spotify-mcp:/app/.cache",
        "-e", "SPOTIPY_CLIENT_ID",
        "-e", "SPOTIPY_CLIENT_SECRET",
        "-e", "SPOTIPY_REDIRECT_URI",
        "-e", "SPOTIPY_CACHE_PATH",
        "docker.io/allesy/spotify-mcp:latest"
      ],
      "env": {
        "SPOTIPY_CLIENT_ID": "your-client-id",
        "SPOTIPY_CLIENT_SECRET": "your-client-secret",
        "SPOTIPY_REDIRECT_URI": "http://127.0.0.1:8888/callback",
        "SPOTIPY_CACHE_PATH": "/app/.cache/token"
      }
    }
  }
}

笔记：

卷装载 ${HOME}/.cache/spotify-mcp:/app/.cache 在运行之间持久化Spotipy的令牌缓存。如果你设置 SPOTIPY_CACHE_PATH，确保它指向下面的某个地方 /app/.cache （例如。， /app/.cache/token).一些MCP客户端不扩展 ${HOME}；如果你看到问题，请使用绝对路径，如 /Users/<you>/.cache/spotify-mcp:/app/.cache.
重定向URI必须与您的Spotify应用程序中配置的URI完全匹配。

首次使用OAuth

Spotipy在首次使用时执行用户授权。

零安装Docker OAuth（推荐）

运行一次此命令以创建并持久化令牌缓存（无需本地安装）：

docker run --rm -it \
  -v ${HOME}/.cache/spotify-mcp:/app/.cache \
  -e SPOTIPY_CLIENT_ID=your-client-id \
  -e SPOTIPY_CLIENT_SECRET=your-client-secret \
  -e SPOTIPY_REDIRECT_URI=http://127.0.0.1:8888/callback \
  -e SPOTIPY_CACHE_PATH=/app/.cache/token \
  docker.io/allesy/spotify-mcp:latest python -u -m spotify_mcp.cli.auth_init

按照提示操作：打开打印的URL，登录，然后将重定向的URL粘贴回终端。令牌保存到 /app/.cache/token （主机上： ${HOME}/.cache/spotify-mcp/token).

之后，您的MCP客户端可以运行服务器容器并自动重用缓存的令牌。

替代方案：本地运行一次

流畅身份验证体验的推荐流程：

安装依赖项并在本地运行身份验证脚本：

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

export SPOTIPY_CLIENT_ID=your-client-id
export SPOTIPY_CLIENT_SECRET=your-client-secret
export SPOTIPY_REDIRECT_URI=http://127.0.0.1:8888/callback
export SPOTIPY_CACHE_PATH=/Users/$(whoami)/.cache/spotify-mcp/token

python -m spotify_mcp.cli.auth_init

按照提示操作：在浏览器中打开URL，授权，然后将重定向URL粘贴回去。
令牌现在已缓存，可以由MCP服务器使用。

或者，您可以让您的MCP客户端在第一次连接时自动处理OAuth（它将打开您的浏览器）。

本地开发（无Docker）

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
export SPOTIPY_CLIENT_ID=...
export SPOTIPY_CLIENT_SECRET=...
export SPOTIPY_REDIRECT_URI=http://127.0.0.1:8888/callback
export PYTHONPATH=src
python -m spotify_mcp.server

您的MCP客户端也可以运行 python -m spotify_mcp.server 如果愿意，直接代替Docker（设置 PYTHONPATH=src 在env中）。

API参考（工具签名）

核心回放和库

搜索（查询：字符串，搜索类型：'track'|'album'|'artist'|'playlist'='track'，限制：int=5，偏移量：int=0）->字符串
play（）->字符串
pause（）->字符串
next_track（）->字符串
previous_track（）->字符串
当前播放（）->字符串
play_song（名称：string）->string
play_by_id（spotify_id_or_uri：字符串）->字符串
list_playlists（限制：int=20，偏移量：int=0）->字符串
list_liked（限制：int=20，偏移量：int=0）->字符串
list_playlist_songs（playlist_id：字符串，限制：int=20，偏移量：int=0）->字符串
add_to_licked（song_ids:string[]）->string
add_to_playlist（playlist_id：字符串，song_ids：字符串[]）->字符串
liked_total（）->int
add_to_queue（track_id：字符串）->字符串
get_queue（）->字符串
get_recently_played（限制：int=20）->字符串
get_top_track（限制：int=20，time_range：string=“medium_term”）->string
get_top_artists（限制：int=20，time_range:string=“medium_term”）->string
list_devices（）->字符串
transfer_playback（设备id：字符串）->字符串
set_shuffle（状态：bool）->字符串
set_repeat（状态：string）->string
seek_position（position_ms:int）->字符串
set_volume（volume_percent:int）->字符串

安全

永远不要泄露秘密。通过MCP客户端配置环境条目提供凭据。
更喜欢挂载缓存目录，而不是将令牌烘焙到映像中。
保持依赖关系更新。

故障排除

身份验证问题

403禁止错误

✅ 检查您的Spotify帐户电子邮件是否已添加到 用户管理 在您的Spotify开发者应用程序中（开发模式需要）
✅ 验证重定向URI是否为 确切地 http://127.0.0.1:8888/callback 两者：
- Spotify开发者仪表板应用程序设置
- 您的MCP客户端配置和身份验证命令

令牌已过期或无效

删除缓存的令牌并重新进行身份验证：

rm ~/.cache/spotify-mcp/token
# Then run the auth_init command again

Docker问题

卷装载路径不工作

一些MCP客户端不扩展 ${HOME} -使用绝对路径，如 /Users/YOUR_USERNAME/.cache/spotify-mcp
在Windows上，使用： C:\Users\YOUR_USERNAME\.cache\spotify-mcp

容器找不到令牌

确保 SPOTIPY_CACHE_PATH MCP配置中的路径与身份验证期间使用的路径匹配(/app/.cache/token)
检查卷装载映射是否正确： -v /local/path:/app/.cache

播放问题

“无活动设备”错误

在尝试播放命令之前，请在任何设备（手机、台式机、网络播放器）上打开Spotify
设备必须正在播放，或者至少在Spotify中打开并可见

命令不起作用

配置更改后重新启动MCP客户端
检查Spotify应用服务器是否正在运行：在MCP客户端的服务器列表中查找

许可证

麻省理工学院