内容
# SpotifyMCP
一款封装了 Spotify Web API 的 MCP 服务器，允许 AI 助手（如 Claude）创建和管理播放列表，搜索音乐，控制播放，以及获取个性化推荐。
## 所有权
该分支由 [**shxfee**](https://github.com/shxfee) 所有和维护。它包含了与上游版本不同的修复和更改，包括加强了对返回非 JSON 成功体的 Spotify 端点的响应处理（例如播放队列）。最初从 [calebWei/SpotifyMCP](https://github.com/calebWei/SpotifyMCP) 分支；感谢原作者为该项目打下的基础。
## 快速设置
### 1. 创建一个 Spotify 应用
每个用户都需要自己的 Spotify 应用以获取 Client ID —— 这是 Spotify 用于识别哪个应用正在发出 API 请求的方式。
1. 前往 [Spotify 开发者仪表盘](https://developer.spotify.com/dashboard) 并创建一个新应用。
2. 在应用设置中，添加以下 **重定向 URI**（确保完全匹配，否则 Spotify 将拒绝登录）：
```
http://127.0.0.1:8888/callback
```
3. 保存并复制您的 **Client ID**。
### 2. 身份验证
运行以下命令一次以登录您的 Spotify 账户。将 `your_client_id_here` 替换为步骤 1 中的 Client ID。它将打开一个浏览器窗口，您批准后，它将保存令牌到 `~/.spotify-mcp/tokens.json`。服务器将自动刷新它们 —— 您不需要再次执行此操作。
**macOS / Linux:**
```bash
SPOTIFY_CLIENT_ID=your_client_id_here npx spotify-mcp@latest auth
```
**Windows (命令提示符):**
```cmd
set SPOTIFY_CLIENT_ID=your_client_id_here && npx spotify-mcp@latest auth
```
**Windows (PowerShell):**
```powershell
$env:SPOTIFY_CLIENT_ID="your_client_id_here"; npx spotify-mcp@latest auth
```
### 3. 配置 Claude Desktop
打开您的 `claude_desktop_config.json`:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** 打开 Claude Desktop → 设置 → 开发者 → 编辑配置
添加 `mcpServers` 块（将 `your_client_id_here` 替换为您的 Client ID）：
```json
{
"mcpServers": {
"spotify": {
"command": "npx",
"args": ["-y", "spotify-mcp@latest"],
"env": {
"SPOTIFY_CLIENT_ID": "your_client_id_here"
}
}
}
}
```
完全退出并重启 Claude Desktop。聊天输入框中的锤子图标确认服务器已连接。
## 使用
连接后，您可以问 Claude：
- "我的 Spotify 热门歌曲是什么？"
- “为学习创建一份轻松的 Lo-Fi 音乐播放列表”
- “将歌曲 Blinding Lights 添加到我的健身播放列表”
- “我最近听过哪些艺术家？”
- “给我创建一个适合深夜驾驶的播放列表”
## 免责声明
该项目是个人项目，与 Spotify 无关，不受 Spotify 支持。它按原样提供，不提供任何类型的保证或担保。请负责任地使用它，并遵守 [Spotify 开发者服务条款](https://developer.spotify.com/terms)。作者不对因使用此软件而产生的任何滥用或后果负责。
## 开发
```bash
git clone https://github.com/shxfee/spotify-mcp.git
cd spotify-mcp
npm install
npm run build
```
复制 `.env.example` 到 `.env` 并填写您的 Client ID，然后：
```bash
npm run auth # 与 Spotify 进行身份验证
npm run dev # 从源代码运行（无需构建）
```
## 分支说明（shxfee/spotify-mcp）
从 [calebWei/SpotifyMCP](https://github.com/calebWei/SpotifyMCP) 分支并针对 Spotify 2026 年 2 月的 Web API 更改进行了修补：
- 统一的 `/me/library` 写端点（`save_items`、`remove_saved_items`、`follow_artist`、`unfollow_artist`）在 **查询字符串** 中接受 `uris`，而不是 JSON 正文。上游代码将它们发送到正文中，这会返回 `400 Missing required field: uris`。已修复为使用查询字符串。
-关注/取消关注艺术家现在通过 `/me/library` 使用 `spotify:artist:<id>` URIs（特定于类型的 `/me/following` 写端点已被删除）。
还要注意：应用程序必须被允许列出（仪表盘 → 用户管理）—— 未被允许列出的用户即使拥有有效的令牌也会收到 `403` 写操作拒绝。
