内容
# Spotify 模型上下文协议（MCP）服务器
<p align="center">
<img src="https://img.shields.io/badge/Python-3.10%2B-blue.svg?style=flat-square" alt="Python 版本">
<img src="https://img.shields.io/badge/Framework-FastMCP-green.svg?style=flat-square" alt="FastMCP">
<img src="https://img.shields.io/badge/API-Spotify%20Web-1DB954?style=flat-square&logo=spotify" alt="Spotify API">
<img src="https://img.shields.io/badge/MCP-Compatible-orange.svg?style=flat-square" alt="MCP 兼容">
<img src="https://img.shields.io/badge/License-MIT-lightgrey.svg?style=flat-square" alt="许可证">
</p>
一个稳健、生产级别的模型上下文协议（MCP）服务器，直接连接 Spotify 的播放、搜索和库管理功能到 LLM 代理（如 Cursor、Claude Desktop 和其他 MCP 客户端）。
使用 **FastMCP** 和 **Spotipy** 在 Python 中构建，该服务器包括连接池、日志隔离和自定义双重身份验证策略，以确保长期稳定性和与非交互式代理的兼容性。
---
## 功能
- **播放控制**：播放曲目/专辑/播放列表、暂停、跳过、调整音量、切换随机播放/重复播放，以及在设备之间转移播放。
- **搜索与发现**：搜索曲目、艺术家、专辑和播放列表，并根据流派/艺术家获取个性化的音乐推荐。
- **库管理**：查看和修改您的“已赞歌曲”库，并创建/管理播放列表。
- **双重身份验证**：本地网页重定向或手动复制粘贴回退，设计为通过代理界面无缝运行。
- **强大的连接处理**：通过 `requests.Session` 进行连接池管理，以及线程安全的自动令牌刷新，以防止内存泄漏和凭证过期崩溃。
- **日志安全**：所有服务器日志和调试输出都隔离到 `stderr`，而 `stdout` 仅用于 MCP 协议消息。
---
## 设置与配置
### 前提条件
- Python 3.10+
- Spotify 账户（需要 Spotify Premium 才能使用播放控制功能）。
### 1. 注册 Spotify 应用
1. 前往 [Spotify 开发者仪表盘](https://developer.spotify.com/dashboard) 并登录。
2. 点击 **创建应用**。
3. 为您的应用命名（例如，“我的 MCP Spotify 服务器”），并添加描述。
4. 在 **重定向 URI** 字段中输入：
`http://127.0.0.1:8080/callback`
5. 在请求的 API 下选中“Web API”框。
6. 点击 **保存**。
7. 在您的新应用设置页面中，获取 **客户端 ID** 和 **客户端密钥**。
### 2. 配置环境变量
在 `Spotify MCP` 文件夹的根目录中创建一个名为 `.env` 的文件：
```env
SPOTIPY_CLIENT_ID=您的_spotify_client_id
SPOTIPY_CLIENT_SECRET=您的_spotify_client_secret
SPOTIPY_REDIRECT_URI=http://127.0.0.1:8080/callback
```
---
## 安装与运行
确保您已创建虚拟环境并安装了依赖项：
```bash
cd "Spotify MCP"
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
### 在本地运行服务器
使用 MCP CLI 工具运行和检查服务器：
```bash
# 激活虚拟环境
source .venv/bin/activate
# 启动开发检查器
mcp dev src/server.py
```
---
## 客户端集成
将服务器添加到您的 MCP 客户端配置中（例如，Cursor、Claude Desktop 或自定义 MCP 客户端）。
例如，在 `claude_desktop_config.json` 中：
```json
{
"mcpServers": {
"spotify": {
"command": "/root/Spotify MCP/.venv/bin/python",
"args": [
"-m",
"src.server"
],
"env": {
"SPOTIPY_CLIENT_ID": "您的_spotify_client_id",
"SPOTIPY_CLIENT_SECRET": "您的_spotify_client_secret",
"SPOTIPY_REDIRECT_URI": "http://127.0.0.1:8080/callback"
}
}
}
}
```
---
## 身份验证流程
由于 MCP 服务器在后台进程中运行，无终端输入，服务器支持流畅的 **双重身份验证** 流程：
### 流程 1：自动本地重定向（默认）
启动时，如果已设置凭证但未授权：
1. 服务器可以尝试打开浏览器登录您的账户。
2. 授权后，Spotify 回调重定向到 `http://127.0.0.1:8080/callback?code=...`，该请求被处理，令牌写入项目根目录下的 `.spotify_token_cache`。
### 流程 2：交互式 LLM/代理身份验证（推荐回退）
如果流程 1 被阻止或您在远程环境中运行代理：
1. 代理将调用 `get_auth_url` 工具。
2. 代理将在聊天中向您显示 Spotify 登录网址。
3. 打开链接，登录，授权，并复制最终重定向的网址（例如，`http://127.0.0.1:8080/callback?code=...`）。
4. 将此网址粘贴回代理。
5. 代理调用 `complete_auth(callback_url)` 工具。
6. 服务器完成身份验证流程，缓存令牌，并立即获得访问权限！
---
## 可用工具
服务器暴露了 25 种工具，分类如下：
| 类别 | 工具 | 描述 |
| :--- | :--- | :--- |
| **系统** | `is_authenticated` | 验证连接状态和登录用户配置文件。 |
| | `get_auth_url` | 生成登录网址以授权 Spotify。 |
| | `complete_auth` | 验证回调重定向并存储令牌。 |
| **播放** | `get_current_playback` | 显示正在播放的内容、活动设备、进度条、音量等。 |
| | `play_track` | 通过名称搜索或确切 URI 播放曲目。 |
| | `play_context` | 通过 URI 播放专辑、播放列表或艺术家。 |
| | `pause_playback` | 暂停 Spotify。 |
| | `next_track` | 跳到队列中的下一首歌曲。 |
| | `previous_track` | 播放历史中的上一首歌曲。 |
| | `set_volume` | 设置音量级别（0 至 100）。 |
| | `get_available_devices` | 列出连接的 Spotify 客户端及其状态和 ID。 |
| | `transfer_playback` | 切换活动播放到另一个设备 ID。 |
| | `toggle_shuffle` | 切换随机播放状态。 |
| | `set_repeat_mode` | 设置重复模式（'track'、'context'、'off'）。 |
| **搜索** | `search_spotify` | 搜索曲目、专辑、艺术家或播放列表。 |
| | `get_recommendations` | 根据种子流派、艺术家或曲目推荐曲目。 |
| | `get_featured_playlists` | 检索当前 Spotify 编辑精选的播放列表。 |
| | `get_lyrics` | 通过网页抓取从 Genius.com 检索歌曲歌词。 |
| **库** | `get_user_playlists` | 列出用户库中的播放列表。 |
| | `create_playlist` | 创建新播放列表。 |
| | `add_to_playlist` | 将曲目（逗号分隔的 URI）添加到播放列表中。 |
| | `get_playlist_tracks` | 列出特定播放列表中的曲目。 |
| | `get_user_saved_tracks` | 列出已赞歌曲。 |
| | `save_tracks` | 将曲目添加到已赞歌曲。 |
| | `remove_tracks` | 从已赞歌曲中删除曲目。 |
---
*项目由 **Gemini Antigravity** 创建，充满爱意。 ❤️*
