使用说明

Spotify MCP 服务器

一个全面的模型上下文协议（MCP）服务器，提供与Spotify Web API的无缝集成。该服务器使AI助手和其他MCP客户端能够与Spotify进行交互，以实现音乐搜索、播放控制、播放列表管理、库操作和用户资料访问等功能。

特点/特性

🎵 搜索功能

轨迹搜索通过歌名、歌手、专辑或歌词查找歌曲
艺术家搜索发现艺术家并探索他们的唱片目录
专辑搜索浏览专辑和合集
播放列表搜索查找公开和协作的播放列表

🎮 播放控制

播放/暂停控制任何连接设备上的音乐播放
轨道导航跳到下一首/上一首曲目
音量控制调整播放音量（0-100%）
播放状态获取当前曲目和设备信息

📝 播放列表管理

创建播放列表创建带有自定义名称和描述的新播放列表
修改播放列表向现有播放列表中添加或删除曲目
播放列表查看用户的个人播放列表和关注的播放列表
播放列表详情访问曲目列表和元数据

📚 图书馆管理

已保存的曲目管理用户喜欢/保存的音乐库
保存/取消保存在个人库中添加或移除曲目
图书馆浏览分页访问已保存的音乐收藏

👤 用户资料与分析

热门曲目获取用户最常播放的歌曲（短期/中期/长期）
顶级艺术家发现不同时期的最爱艺术家
近期历史访问最近播放的曲目及其时间戳
听力洞察了解音乐偏好和模式

快速入门

先决条件

Spotify开发者账户在（某网站/平台）创建一个免费账户 Spotify开发者平台
Spotify应用程序注册一个新应用以获取客户端ID和客户端密钥
Docker （用于容器化部署）或 Python 3.11+ （用于本地开发）

Spotify 应用配置

首选 Spotify开发者仪表板
点击“创建应用”
填写应用详情：
- 应用名称您的应用名称（例如，“我的MCP服务器”）
- 应用描述您的用例简要描述
创建后，请记下您的 客户端ID 并且 客户端密钥
添加重定向URI： http://localhost:8080 （用于本地OAuth流程）

Docker 部署（推荐）

克隆并设置:

git clone <repository-url>
cd spotify-mcp-server

# Copy environment template
cp .env.example .env

配置环境：编辑 .env 包含您的Spotify凭据的文件：

SPOTIFY_CLIENT_ID=your_actual_client_id
SPOTIFY_CLIENT_SECRET=your_actual_client_secret

构建并运行:

# Build the Docker image
docker-compose build

# Start the server
docker-compose up -d

# View logs
docker-compose logs -f spotify-mcp-server

本地开发

设置Python环境:

# Clone repository
git clone <repository-url>
cd spotify-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\\Scripts\\activate

# Install dependencies
pip install -r requirements.txt

配置环境变量：

export SPOTIFY_CLIENT_ID="your_client_id"
export SPOTIFY_CLIENT_SECRET="your_client_secret"

运行服务器:

# Direct execution
python run_server.py

# Or as module
python -m src.server

MCP客户端集成

Claude 桌面配置

添加到您的Claude桌面配置中（~/AppData/Roaming/Claude/config.json 在Windows上或 ~/Library/Application Support/Claude/config.json （在 macOS 上）：

{
  "mcpServers": {
    "spotify": {
      "command": "python",
      "args": ["/path/to/spotify-mcp-server/run_server.py"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Docker 集成

{
  "mcpServers": {
    "spotify": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "SPOTIFY_CLIENT_ID=your_client_id",
        "-e",
        "SPOTIFY_CLIENT_SECRET=your_client_secret",
        "spotify-mcp-server"
      ]
    }
  }
}

可用工具

搜索工具

`search_tracks`

搜索音乐曲目

查询（字符串，必填）：搜索词
限制 (整数，可选)：结果限制（1-50，默认：20）

`search_artists`

寻找艺术家和乐队

查询（字符串，必填）：艺术家搜索词
限制（整数，可选）：结果限制（1-50，默认：20）

`search_albums`

发现专辑和合集

查询（字符串，必填）：专辑搜索词
限制（整数，可选）：结果限制（1-50，默认：20）

`search_playlists`

查找公开播放列表

查询 (字符串，必填)：播放列表搜索词
限制（整数，可选）：结果限制（1-50，默认：20）

播放控制工具

`get_current_playback`

获取当前播放状态和曲目信息

`play_music`

开始或恢复播放

设备ID (字符串，可选)：目标设备ID
上下文URI (字符串，可选)：要播放的专辑/播放列表URI
track_uris 翻译为中文是“音轨URI（统一资源标识符）” （数组，可选）：要播放的特定曲目URI

`pause_music`

暂停当前播放

设备ID （字符串，可选）：目标设备ID

`next_track`

跳到下一首曲目

设备ID （字符串，可选）：目标设备ID

`previous_track`

跳到上一曲

设备ID （字符串，可选）：目标设备ID

`set_volume`

控制播放音量

音量（整数，必填）：体积百分比（0-100）
设备ID (字符串，可选)：目标设备ID

播放列表管理工具

`get_user_playlists`

列出用户的播放列表

限制（整数，可选）：播放列表的数量（1-50，默认：20）

`create_playlist`

创建一个新的播放列表

名字 (字符串，必填)：播放列表名称
描述 (字符串，可选)：播放列表描述
公共的 （布尔型，可选）：公开可见性（默认：false）

`add_tracks_to_playlist`

将曲目添加到播放列表

播放列表ID (字符串，必填)：目标播放列表ID
track_uris（在中文语境下，可翻译为“音轨URI列表”或根据具体上下文简化为“音轨链接列表”，但“track_uris”本身作为一个术语或特定用语时，可能直接保留原样以避免歧义） (数组，必需)：要添加的曲目URI

`remove_tracks_from_playlist`

从播放列表中移除曲目

播放列表ID (字符串，必填)：目标播放列表ID
track_uris 翻译成中文是“音轨URI”或“曲目URI”，其中“URI”代表“统一资源标识符”（Uniform Resource Identifier） （数组，必需）：要移除的曲目URI

图书馆管理工具

`get_saved_tracks`

获取用户收藏/喜欢的曲目

限制（整数，可选）：结果限制（1-50，默认：20）
偏移量 (整数，可选)：分页偏移量（默认：0）

`save_tracks`

将轨迹保存到用户的库中

轨道ID（或曲目ID，根据上下文可能有所不同） （数组，必填）：要保存的曲目ID

`remove_saved_tracks`

从用户的库中移除曲目

轨道ID（或曲目ID） （数组，必填）：要移除的轨道ID

用户配置文件工具

`get_top_tracks`

获取用户最常播放的曲目

限制（整数，可选）：结果限制（1-50，默认：20）
时间范围 （字符串，可选）：时间段（“短期”，“中期”，“长期”）

`get_top_artists`

获取用户喜爱的艺术家

限制（整数，可选）：结果限制（1-50，默认：20）
时间范围 （字符串，可选）：时间段（“短期”，“中期”，“长期”）

`get_recently_played`

获取最近播放的曲目

限制（整数，可选）：结果限制（1-50，默认：20）

示例用法

搜索并播放音乐

# Search for tracks
search_tracks(query="bohemian rhapsody queen")

# Play specific track
play_music(track_uris=["spotify:track:4u7EnebtmKWzUH433cf5Qv"])

# Control playback
pause_music()
next_track()
set_volume(volume=75)

播放列表管理

# Create new playlist
create_playlist(name="My AI Playlist", description="Created by AI assistant")

# Add tracks to playlist
add_tracks_to_playlist(
    playlist_id="37i9dQZF1DX0XUsuxWHRQd",
    track_uris=["spotify:track:4u7EnebtmKWzUH433cf5Qv"]
)

发现用户偏好

# Get top tracks
get_top_tracks(limit=10, time_range="short_term")

# Get recent history
get_recently_played(limit=20)

# Get favorite artists
get_top_artists(limit=5, time_range="long_term")

认证流程

服务器使用Spotify的带有PKCE的授权码流程进行安全认证：

初始设置服务器生成授权URL
用户同意用户访问URL并授予权限
代币兑换服务器用授权码交换访问/刷新令牌
令牌管理令牌过期时自动刷新
持久会话本地缓存令牌，实现无缝体验

所需的Spotify权限范围

服务器请求这些OAuth范围以实现全部功能：

user-read-private - 用户资料访问
user-read-email - 用户电子邮件（用于身份验证）
user-read-playback-state - 当前播放信息
user-modify-playback-state - 播放控制
user-read-currently-playing - 正在播放的曲目
user-read-recently-played - 收听历史
user-top-read - 热门曲目和艺术家
user-library-read - 访问已保存的音乐
user-library-modify - 修改已保存的音乐
playlist-read-private - 私人播放列表
playlist-read-collaborative - 共享播放列表
playlist-modify-private - 编辑私人播放列表
playlist-modify-public - 编辑公开播放列表
streaming - 播放控制

建筑学

组件概述

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │────│  Spotify MCP     │────│  Spotify Web    │
│   (Claude AI)   │    │     Server       │    │      API        │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                         ┌──────▼──────┐
                         │   Tools &   │
                         │ Capabilities│
                         └─────────────┘

关键组件

**server.py**主要的MCP服务器实现，使用stdio传输
**spotify_client.py**Spotify Web API封装，支持OAuth2认证
**tools.py**MCP工具定义和请求处理程序
**run_server.py**用于轻松执行的入口点脚本

错误处理

认证错误优雅地处理过期/无效令牌
API速率限制自动重试，采用指数退避策略
网络问题强大的错误报告和恢复机制
无效请求全面的输入验证和错误信息提示

故障排除

常见问题

认证问题

# Error: "Authentication failed"
# Solution: Check credentials and redirect URI
export SPOTIFY_CLIENT_ID="correct_client_id"
export SPOTIFY_CLIENT_SECRET="correct_client_secret"

权限错误

# Error: "Insufficient scope"
# Solution: Ensure all required scopes are approved
# Check your Spotify app settings and re-authenticate

播放问题

# Error: "No active device"
# Solution: Start Spotify on any device before controlling playback
# The device must be active for remote control

调试模式

启用详细日志记录：

# Set environment variable
export LOG_LEVEL=DEBUG

# Or modify server.py logging level
logging.basicConfig(level=logging.DEBUG)

Docker 故障排除

# Check container logs
docker-compose logs spotify-mcp-server

# Interactive container debugging
docker-compose exec spotify-mcp-server bash

# Rebuild after changes
docker-compose build --no-cache

发展

本地开发环境设置

安装开发依赖项:

pip install -r requirements.txt
pip install pytest black flake8 mypy

运行测试：
```
pytest tests/
```
代码格式化:
```
black src/
flake8 src/
mypy src/
```

项目结构

spotify-mcp-server/
├── src/
│   ├── __init__.py
│   ├── server.py          # Main MCP server
│   ├── spotify_client.py  # Spotify API wrapper
│   └── tools.py          # MCP tool definitions
├── tests/                # Test suite
├── requirements.txt      # Python dependencies
├── Dockerfile           # Container definition
├── docker-compose.yml   # Container orchestration
├── run_server.py       # Entry point script
├── .env.example        # Environment template
└── README.md          # Documentation

安全考虑事项

凭证；资格永远不要将API密钥提交到版本控制系统中
令牌存储令牌已本地缓存 - 请确保您的环境安全
网络在生产环境中使用HTTPS
权限请求最小必要的OAuth范围
集装箱安全在Docker中以非root用户身份运行

做出贡献

为仓库创建分支（或“克隆仓库”）
创建一个特性分支（git checkout -b feature/amazing-feature)
提交更改（git commit -m 'Add amazing feature')
推送到分支（git push origin feature/amazing-feature)
提交拉取请求（或：创建合并请求）

许可证

此项目采用MIT许可证授权——详见LICENSE文件。

致谢

Spotify Web API 为了全面访问音乐数据
Spotipy（注：Spotipy是一个用于与Spotify API进行交互的Python库，此翻译为直译，实际使用时可能根据上下文有所调整）用于Python Spotify API集成
模型上下文协议用于标准化人工智能工具集成
Anthropic（公司名，可译为“安萨提克”或根据语境保持原名不译）用于MCP开发和Claude集成

音乐发现愉快！ 🎵

如需支持或有疑问，请在仓库中提交一个问题或查阅Spotify开发者文档。

使用说明

Spotify MCP 服务器

特点/特性

🎵 搜索功能

🎮 播放控制

📝 播放列表管理

📚 图书馆管理

👤 用户资料与分析

快速入门

先决条件

Spotify 应用配置

Docker 部署（推荐）

本地开发

MCP客户端集成

Claude 桌面配置

Docker 集成

可用工具

搜索工具

search_tracks

search_artists

search_albums

search_playlists

播放控制工具

get_current_playback

play_music

pause_music

next_track

previous_track

set_volume