内容
# Yandex 音乐 MCP 服务器
用于在 Yandex 音乐上创建播放列表的 MCP 服务器。围绕 [yandex-music-api](https://github.com/MarshalX/yandex-music-api) 的薄封装。
## 功能
通过 stdio 暴露了三个 MCP 工具：
- `create_playlist(title, visibility="public")` — 创建一个新的播放列表。
- `search_tracks(query, limit=10)` — 通过自由文本查询搜索曲目，返回 `track_id` 和 `album_id`。
- `add_tracks_to_playlist(kind, tracks)` — 将找到的曲目添加到播放列表中。
需要 Python 3.8+。
## 使用 `uvx` 快速开始（无需安装）
如果你有 [`uv`](https://github.com/astral-sh/uv)：
```bash
# 一次性：获取令牌
uvx --from git+https://github.com/lappi/yandex-music-mcp yandex-music-mcp-token
# 运行服务器
YANDEX_MUSIC_TOKEN=<token> \
uvx --from git+https://github.com/lappi/yandex-music-mcp yandex-music-mcp
```
一旦软件包发布到 PyPI，`--from ...` 标志将不再需要。
## 使用 pip 安装
```bash
git clone https://github.com/lappi/yandex-music-mcp
cd yandex-music-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .
```
这会在 venv 中创建两个控制台脚本：
- `yandex-music-mcp` — MCP 服务器。
- `yandex-music-mcp-token` — OAuth 设备流令牌助手。
## 获取令牌
**推荐 — OAuth 设备流：**
```bash
yandex-music-mcp-token
```
命令打印一个 URL (`https://ya.ru/device`) 和一个短代码。在任何浏览器中打开 URL，登录到您的 Yandex 帐户并输入代码。访问令牌打印到 stdout。
一行命令到环境变量：
```bash
export YANDEX_MUSIC_TOKEN=$(yandex-music-mcp-token)
```
**注意事项：** 助手使用 Yandex 音乐移动应用的 `client_id`/`client_secret`（公开已知）。Yandex 音乐没有官方公共 API — 这在技术上违反了服务条款，因此请自担风险使用。
替代令牌来源：https://music-yandex-bot.ru/，浏览器扩展，Android APK — 请参阅 [yandex-music-api 令牌文档](https://yandex-music.readthedocs.io/en/main/token.html)。
## 运行服务器
```bash
YANDEX_MUSIC_TOKEN=<token> yandex-music-mcp
```
或作为模块：
```bash
python -m yandex_music_mcp
```
服务器通过 stdio 讲话 MCP 并等待客户端。
## 连接到 Claude Code / Claude Desktop
在您的 MCP 配置中添加一个条目：
- Claude Code：`~/.claude.json`
- Claude Desktop（macOS）：`~/Library/Application Support/Claude/claude_desktop_config.json`
- Claude Desktop（Windows）：`%APPDATA%\Claude\claude_desktop_config.json`
### 使用 `uvx`（推荐给最终用户）
```json
{
"mcpServers": {
"yandex-music": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/lappi/yandex-music-mcp",
"yandex-music-mcp"
],
"env": { "YANDEX_MUSIC_TOKEN": "<your-token>" }
}
}
}
```
### 使用本地 venv
```json
{
"mcpServers": {
"yandex-music": {
"command": "/absolute/path/to/yandex-music-mcp/.venv/bin/yandex-music-mcp",
"env": { "YANDEX_MUSIC_TOKEN": "<your-token>" }
}
}
}
```
在编辑配置后，请完全退出并重新启动 Claude Desktop（`Cmd+Q` / `Alt+F4`）— 关闭窗口不会重新加载它。
## 使用 MCP Inspector 进行调试
```bash
YANDEX_MUSIC_TOKEN=<token> npx @modelcontextprotocol/inspector yandex-music-mcp
```
## 示例用法
询问 LLM： *"创建一个播放列表 'Classic Rock' 并添加 5 首 Queen 曲目到它。"*
LLM 将链接 `create_playlist` → `search_tracks` → `add_tracks_to_playlist`。
## 许可证
MIT。本项目与 Yandex 无关联或未得到 Yandex 的认可。
