Yandex Music (unofficial)

yandex-music-mcp

面向Яндекс Музыки的非官方 MCP 服务。可连接 Claude Desktop、Claude Code 和其他 MCP 客户端，让助手访问你的音乐库：点赞、收听历史、“我的电波”和播放列表。

服务在你的电脑上本地运行（stdio）。令牌仅保存在你的设备上，不会传到任何地方。支持 Windows、macOS 和 Linux。

⚠️ 非官方项目。 与 ООО «Яндекс» 无关，也未经其认可。项目使用非官方库 yandex-music：如果 Яндекс 更改 API，服务可能会暂时无法运行。服务不会下载音频，仅处理你账户中的元数据、点赞和播放列表。

下方提供英文版 ↓

---

功能

读取	修改
account_info — 检查连接	create_playlist — 新建播放列表（默认设为私密）
search — 搜索曲目、专辑、艺人和播放列表	add_tracks_to_playlist — 添加曲目
get_liked_tracks — “我喜欢的”	remove_tracks_from_playlist — 移除曲目
get_listening_history — 按天查看收听历史	delete_playlist — 删除播放列表（会检查名称）
list_my_playlists, get_playlist_tracks — 你的播放列表	like_tracks / unlike_tracks — 点赞 / 取消点赞
get_playlist_by_url — 根据链接获取任意公开播放列表或专辑	export_tracks_to_file — 将点赞曲目或播放列表导出为 .txt 和 .csv
get_album_tracks, get_artist_tracks — 专辑和艺人
get_similar_tracks, get_my_wave, get_chart — 推荐和榜单

服务不控制播放：你照常在 Яндекс Музыки 应用中听音乐，新建的播放列表和点赞会立即显示在应用中。

请求示例

• “分析我最近点赞的 300 首曲目：我听哪些流派和年代的音乐？”
• “我这周听了什么？”
• “根据我最近点赞的曲目，创建一个包含 25 首相似曲目的私密播放列表‘秋天’”
• “这是朋友的播放列表：<链接>。其中有哪些曲目已经在我的点赞里了？”
• “将我所有点赞的曲目导出到文件”

---

快速安装

1. 安装 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 检查。

2. 登录 Яндекс（只需一次）：

uvx --from yandex-music-mcp yandex-music-mcp-auth

3. 连接到客户端：

• 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 和 Яндекс 账户。部分功能（例如“我的电波”）可能需要 Plus 订阅。

1. 安装 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 检查。

2. 下载项目

git clone https://github.com/kenzolika/yandex-music-mcp.git

也可以在仓库页面点击 Code → Download ZIP，然后解压存档。

3. 获取令牌（只需一次）

cd yandex-music-mcp
uv run yandex-music-mcp-auth

浏览器会打开 Яндекс 登录页面（ya.ru/device），终端中会显示一个代码。登录账户，输入代码，并等待终端显示“完成！”令牌将保存在 ~/.yandex-music-mcp/token 中。脚本使用 Яндекс 官方登录方式，不会获取你的密码。

4. 查找项目文件夹的完整路径

客户端需要知道项目所在的位置。最简单的方法是在终端中进入项目文件夹（完成第 3 步后，你已经位于其中）：

• Windows（PowerShell）： (Get-Location).Path → 例如，C:\Users\Ivan\Documents\yandex-music-mcp
• macOS / Linux： pwd → 例如，/Users/ivan/yandex-music-mcp

在 Windows 上也可以用鼠标操作：在文件资源管理器中按住 Shift，右键单击文件夹，然后选择 “复制为路径”。

Windows 重要提示： JSON 配置中的反斜杠需要重复两次：C:\\Users\\Ivan\\Documents\\yandex-music-mcp。也可以改用正斜杠，Windows 也能识别：C:/Users/Ivan/Documents/yandex-music-mcp。

5а. 连接到 Claude Desktop

在 Claude Desktop 中打开 Settings → Developer → Edit Config，这会打开文件 claude_desktop_config.json。将 mcpServers 代码块添加到文件中，并填入第 4 步获取的路径：

{
  "mcpServers": {
    "yandex-music": {
      "command": "uv",
      "args": ["--directory", "C:/Users/Ivan/Documents/yandex-music-mcp", "run", "yandex-music-mcp"]
    }
  }
}

• 文件中已有其他设置？ 不要删除它们：在顶层与其他设置并列添加 "mcpServers": { ... }，并用逗号分隔。
• Claude 找不到 uv？ 在 "command" 中填写它的完整路径。可通过 where.exe uv（Windows）或 which uv（macOS/Linux）查看路径，通常是 C:/Users/Ivan/.local/bin/uv.exe 或 ~/.local/bin/uv。

完全退出 Claude Desktop（Windows 上通过系统托盘图标 → Quit 退出；仅关闭窗口还不够），然后重新打开。

5б. 或连接到 Claude Code

用第 4 步获取的路径运行一条命令，替代第 5а 步：

claude mcp add yandex-music -- uv --directory "C:/Users/Ivan/Documents/yandex-music-mcp" run yandex-music-mcp

6. 检查

在新聊天中输入：“检查与 Yandex Music 的连接”。如果回复中显示了你的登录名，就说明一切正常。

---

设置

变量	用途
YANDEX_MUSIC_TOKEN	直接提供令牌（代替文件）
YANDEX_MUSIC_TOKEN_FILE	令牌文件的路径
YANDEX_MUSIC_EXPORT_DIR	导出文件的保存位置（默认为 Документы/Yandex Music exports）

安全与隐私

• 令牌可完全访问你的 Music 账户。请勿公开令牌或将其加入 git——.gitignore 已排除令牌文件和导出文件。
• 可在 id.yandex.ru 的设备和服务部分撤销访问权限。
• 所有会执行更改的工具都已标记为会修改数据，MCP 客户端会据此处理；Claude 默认会在调用前询问确认。delete_playlist 还要求提供准确的播放列表名称。

故障排除

• Claude 中没有显示服务。 检查 JSON 中是否有多余或缺失的逗号，以及项目路径和 uv 路径是否正确。日志位置：%APPDATA%\Claude\logs\mcp-server-yandex-music.log（Windows）或 ~/Library/Logs/Claude/（macOS）。
• “没有令牌”。 再次执行第 3 步，并且不要关闭终端，直到出现“完成！”。错误消息中列出了服务查找令牌的位置。
• 更新后看不到新工具。 重启 Claude 并打开新聊天。

---

English

适用于 Yandex Music 的非官方 MCP 服务。它将 Claude Desktop、Claude Code 和其他 MCP 客户端连接到你的 Yandex Music 曲库，包括喜欢的内容、收听历史、My Wave 和播放列表。

服务在本地计算机上运行（stdio）。令牌仅存储在你的计算机上，不会发送到其他任何地方。支持 Windows、macOS 和 Linux。

⚠️ 非官方项目。 与 Yandex 无关，也未获其认可。该项目基于非官方的 yandex-music 库构建，因此如果 Yandex 更改其 API，服务可能会暂时无法使用。该服务不会下载音频；它仅处理账户中的元数据、喜欢的内容和播放列表。

工具

读取	写入
account_info — 检查连接	create_playlist — 创建新播放列表（默认设为私密）
search — 搜索曲目、专辑、艺人和播放列表	add_tracks_to_playlist
get_liked_tracks — 你点赞的曲目	remove_tracks_from_playlist
get_listening_history — 按日期查看历史记录	delete_playlist — 删除播放列表（需要提供其准确标题）
list_my_playlists、get_playlist_tracks — 你的播放列表	like_tracks / unlike_tracks
get_playlist_by_url — 通过链接获取任何公开的播放列表或专辑	export_tracks_to_file — 将点赞或播放列表导出为 .txt 和 .csv 文件
get_album_tracks、get_artist_tracks
get_similar_tracks、get_my_wave、get_chart — 推荐和排行榜

该服务不控制播放：照常在 Yandex Music 应用中收听；新建的播放列表和点赞会立即显示在那里。

提示词示例：“分析我最近点赞的 300 首曲目：我听哪些流派和年代的音乐？” · “我这周听了什么？” · “创建一个私密播放列表 ‘Autumn’，包含 25 首与我最近点赞的曲目相似的曲目” · “这是我朋友的播放列表：。其中哪些曲目已经在我的点赞列表中？” · “将我所有点赞导出到文件”

快速安装

1. 安装 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 检查。
2. 登录 Yandex（仅需一次）：uvx --from yandex-music-mcp yandex-music-mcp-auth
3. 连接客户端：
   • 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"] }
       }
     }
     

从源代码安装

1. 安装 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 检查。
2. 获取代码： 运行 git clone https://github.com/kenzolika/yandex-music-mcp.git，或在仓库页面选择 Code → Download ZIP。
3. 获取令牌（仅需一次）： 运行 cd yandex-music-mcp，然后运行 uv run yandex-music-mcp-auth。系统会打开 Yandex 登录页面（ya.ru/device），终端中会显示一个代码。登录，输入代码，然后等待出现 "Готово!"（“完成！”）这一行。令牌会保存到 ~/.yandex-music-mcp/token。这是 Yandex 官方的 OAuth 设备授权流程；脚本不会获取你的密码。
4. 找到项目文件夹的完整路径。 在项目文件夹中运行 (Get-Location).Path（Windows PowerShell）或 pwd（macOS/Linux）。在 Windows 上，也可以在资源管理器中按住 Shift 并右键单击文件夹 → Copy as path。在 JSON 中，可以将反斜杠加倍（C:\\Users\\Ivan\\yandex-music-mcp），也可以使用正斜杠（C:/Users/Ivan/yandex-music-mcp）。
5. 连接客户端。
   • 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
6. 检查： 在新聊天中询问“检查我的 Yandex Music 连接”。如果回答中显示了你的登录信息，就表示一切就绪。

配置

变量	用途
YANDEX_MUSIC_TOKEN	直接传入令牌，无需使用文件
YANDEX_MUSIC_TOKEN_FILE	令牌文件的路径
YANDEX_MUSIC_EXPORT_DIR	导出文件的保存位置（默认：Documents/Yandex Music exports）

安全与隐私

• 该令牌可完全访问你的 Yandex Music 账户。切勿公开或提交该令牌；.gitignore 已排除令牌文件和导出文件。
• 你可以在 id.yandex.ru 的“设备和服务”中撤销访问权限。
• 所有会修改内容的工具都会向 MCP 客户端标记这一点，因此 Claude 会在调用前请求确认。delete_playlist 还要求提供播放列表的准确标题。

故障排除

• Claude 中没有显示该服务。 检查 JSON 是否缺少或多出逗号、项目路径以及 uv 的路径。日志：%APPDATA%\Claude\logs\mcp-server-yandex-music.log（Windows）或 ~/Library/Logs/Claude/（macOS）。
• “No token”错误。 再次执行第 3 步，并保持终端打开，直到出现“Готово!”。错误消息会列出该服务查找令牌的所有路径。
• 更新后缺少新工具。 重启 Claude 并开启新聊天。

---

作者 · 作者

由 Kenzolika & Claudiea 🎧 制作——一个人和他的 AI 搭档（Claude）在一个秋日的傍晚完成。 由 Kenzolika & Claudiea 制作，一个人与他的 AI 搭档（Claude）在一个秋日傍晚共同完成。

许可证 · 许可证

MIT，详见 LICENSE。使用 yandex-music 库（LGPL-3.0）作为未经修改的依赖项。 MIT，详见 LICENSE。使用 yandex-music（LGPL-3.0）作为未经修改的依赖项。