yandex-music-mcp 是一个非官方的 MCP（Model Context Protocol）服务器，用于将 Claude Desktop、Claude Code 及其他 MCP 客户端连接到用户的 Yandex Music 账户。它让 AI 助手能够访问用户的音乐库，包括点赞、收听历史、My Wave 和播放列表。
用途 该服务器的主要用途是让 AI 助手基于用户的 Yandex Music 数据执行查询和操作。例如，分析最近 300 个点赞的流派和年代分布、查看本周收听记录、根据最近点赞创建包含 25 首相似曲目的私密播放列表、检查朋友分享的播放列表中哪些曲目已在用户点赞中，以及将全部点赞导出到文件。
主要能力 服务器提供对以下内容的访问：搜索、点赞、收听历史、My Wave、播放列表。支持按链接查看公开播放列表、管理播放列表，以及将音乐库导出为 TXT/CSV 格式。所有会修改数据的工具在 MCP 客户端中标记为“修改类”，Claude 默认会在调用前请求确认；delete_playlist 还要求提供播放列表的准确名称。
使用方式 服务器在本地以 stdio 方式运行，令牌仅存储在用户电脑上，不会发送到其他地方。支持 Windows、macOS 和 Linux。
快速安装：
- 安装 uv： Windows (PowerShell)：powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" macOS / Linux：curl -LsSf https://astral.sh/uv/install.sh | sh 关闭终端后重新打开，检查：uv --version
- 登录 Yandex（一次）：uvx --from yandex-music-mcp yandex-music-mcp-auth
- 连接客户端： Claude Code：claude mcp add yandex-music -- uvx yandex-music-mcp Claude Desktop：打开 Settings → Developer → Edit Config，在 claude_desktop_config.json 中添加： { "mcpServers": { "yandex-music": { "command": "uvx", "args": ["yandex-music-mcp"] } } }
从源码安装：
- 安装 uv（同上）。
- 获取代码：git clone https://github.com/kenzolika/yandex-music-mcp.git，或在仓库页面点击 Code → Download ZIP。
- 获取令牌（一次）：cd yandex-music-mcp，然后 uv run yandex-music-mcp-auth。会打开 Yandex 登录页面（ya.ru/device），终端显示代码。登录并输入代码，等待出现“Готово!”（“完成！”）。令牌保存到 ~/.yandex-music-mcp/token。该脚本使用 Yandex 官方 OAuth 设备流程，不会看到密码。
- 获取项目文件夹的完整路径：在项目文件夹中运行 (Get-Location).Path（Windows PowerShell）或 pwd（macOS/Linux）。Windows 也可在资源管理器中 Shift + 右键文件夹 → 复制为路径。在 JSON 中，反斜杠需双写（C:\Users\Ivan\yandex-music-mcp）或使用正斜杠（C:/Users/Ivan/yandex-music-mcp）。
- 连接客户端： Claude Desktop：Settings → Developer → Edit Config 打开 claude_desktop_config.json，添加： { "mcpServers": { "yandex-music": { "command": "uv", "args": ["--directory", "/absolute/path/to/yandex-music-mcp", "run", "yandex-music-mcp"] } } } 保留已有设置，在顶层添加 "mcpServers" 并用逗号分隔。如果 Claude 找不到 uv，在 "command" 中填写其完整路径（Windows 用 where.exe uv，macOS/Linux 用 which uv）。然后完全退出 Claude Desktop（Windows：托盘图标 → Quit）并重新启动。 Claude Code：claude mcp add yandex-music -- uv --directory /absolute/path/to/yandex-music-mcp run yandex-music-mcp
- 检查：在新聊天中询问“检查我的 Yandex Music 连接”。如果回答显示你的登录名，则一切正常。
适用场景 适用于希望让 AI 助手分析个人音乐收听习惯、管理播放列表、导出点赞数据，或基于现有喜好生成新播放列表的用户。需要已安装 uv 和 Yandex 账户；部分功能（如 My Wave）可能需要 Plus 订阅。
限制 该项目为非官方项目，与 Yandex 无关联且未获其认可。基于非官方库 yandex-music 构建，如果 Yandex 更改 API，服务器可能暂时无法工作。服务器不下载音频，仅处理账户中的元数据、点赞和播放列表。服务器不控制播放：音乐仍在 Yandex Music 应用中正常收听，新播放列表和点赞会立即显示在那里。令牌提供对 Yandex Music 账户的完全访问权限，请勿公开或提交到 git；.gitignore 已排除令牌文件和导出文件。可在 id.yandex.ru 的设备和服务中撤销访问权限。
故障排除 服务器未出现在 Claude 中：检查 JSON 是否有缺失或多余逗号、项目路径和 uv 路径。日志位置：%APPDATA%\Claude\logs\mcp-server-yandex-music.log（Windows）或 ~/Library/Logs/Claude/（macOS）。 “无令牌”错误：重新执行第 3 步，并保持终端打开直到出现“Готово!”。错误消息会列出服务器查找令牌的所有路径。 更新后缺少新工具：重启 Claude 并打开新聊天。
作者与许可 由 Kenzolika & Claudiea 制作。MIT 许可证，详见 LICENSE。使用 yandex-music（LGPL-3.0）作为未修改的依赖项。
