内容
# 云音乐桌面端MCP
一个小型、仅限本地的MCP服务器，允许AI控制Windows上的官方网易云音乐桌面端。
它通过桌面端自己的API（带有匿名HTTPS备用方案）进行搜索，通过官方`orpheus://`协议打开一次性选择，并通过仅限本地的Chromium控制通道控制队列、播放模式、桌面歌词和应用程序音量。它不会取代官方播放器或创建第二个播放进程。
> 这是一个独立的社区项目。它与网易云音乐无关、不受其支持或认可。
## 前提条件
- Windows 10 或 Windows 11。
- 已安装官方网易云音乐桌面端。
- 建议在桌面端登录个人账户。该账户决定了客户端可以播放哪些已订阅或付费的曲目。
- Python 3.11 或更新版本。
- 可以启动stdio服务器的本地MCP主机，例如Codex或Claude Desktop。
MCP永远不会读取已登录的账户、浏览器cookie、凭证、收听历史、播放列表或本地音乐库。
## 安装
```powershell
git clone https://github.com/Seraph310/cloudmusic-desktop-mcp.git
cd cloudmusic-desktop-mcp
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
```
如果可执行文件安装在非标准网易云音乐目录之外，请在MCP配置中将其完整路径设置为`CLOUDMUSIC_EXE`。
### Codex 配置
将以下内容添加到`%USERPROFILE%\.codex\config.toml`中，替换两个路径：
```toml
[mcp_servers.cloudmusic]
command = 'C:\path\to\cloudmusic-desktop-mcp\.venv\Scripts\python.exe'
args = ['C:\path\to\cloudmusic-desktop-mcp\server.py']
startup_timeout_sec = 30
[mcp_servers.cloudmusic.env]
CLOUDMUSIC_EXE = 'C:\path\to\CloudMusic\cloudmusic.exe'
```
在更改MCP主机的配置后，请重新启动它。
## 工具
| 工具 | 用途 |
| --- | --- |
| `get_netease_status` | 检查配置的可执行文件和运行状态 |
| `launch_netease_music` | 启动官方桌面端 |
| `search_music` | 搜索歌曲或播放列表而不播放 |
| `search_and_play` | 搜索并播放明确的匹配结果 |
| `play_netease_item` | 播放已知的数字歌曲或播放列表ID |
| `get_netease_queue` | 读取队列、当前歌曲、模式、应用程序音量和桌面歌词状态 |
| `set_netease_queue` | 用有序的数字歌曲ID替换队列 |
| `clear_netease_queue` | 停止播放并清空当前队列 |
| `search_and_set_netease_queue` | 搜索多个短语并按该顺序建立队列 |
| `add_to_netease_queue` | 将歌曲插入队列或添加到队列末尾 |
| `set_netease_play_mode` | 选择顺序、列表循环、单曲循环或随机播放 |
| `set_netease_volume` | 设置应用程序独立的0-100播放器音量 |
| `set_desktop_lyrics` | 显式显示或隐藏桌面歌词 |
| `set_desktop_lyrics_theme` | 选择官方桌面歌词颜色主题 |
| `control_netease` | 播放/暂停、停止、跳过、静音或使用Windows音量键 |
| `send_netease_shortcut` | 发送允许的喜欢、歌词或迷你模式快捷方式 |
当提供艺术家时，`search_and_play`除非找到一个确切的标准化标题/艺术家匹配结果，否则拒绝播放。这避免了无声选择封面版本。必须首先将可选的应用程序快捷方式配置为与网易云音乐中的匹配全局快捷方式。
高级状态工具需要使用本地控制通道启动云音乐。如果`get_netease_status`报告`queue_control_ready: false`，请关闭云音乐一次并调用`launch_netease_music`。MCP启动它时，通道绑定到`127.0.0.1`的`9223`端口。在MCP环境中设置`CLOUDMUSIC_CDP_PORT`以选择另一个本地端口。
播放模式为`order`、`list_loop`、`single_loop`和`shuffle`。`set_netease_volume`仅更改云音乐自己的音量，而不是Windows主音量。`set_desktop_lyrics`在操作前读取当前状态，因此重复请求不会意外地将其切换到错误的方向。
桌面歌词主题有`netease_red`、`sunset`、`cute_pink`、`sky_blue`、`fresh_green`、`vivid_purple`、`warm_yellow`和`soft_gray`。
## 测试环境
- Windows 11 64位，版本`26200`。
- 网易云音乐桌面端`3.1.24.204791`。
- Python `3.11.5`。
其他最近的Windows客户端版本可能有效，但尚未经过验证。
## 安全选择
- 仅HTTPS搜索。
- 无Selenium、ChromeDriver、cookie或账户凭证。
- 高级控制仅绑定到`127.0.0.1`，且从不远程暴露。
- 仅评估固定、允许的客户端操作以及验证的歌曲ID和设置。
- 无任意命令、URL、键盘输入或shell执行。
- 不会终止或重启现有的云音乐进程。
- 仅打开由数字结果ID构建的允许的`orpheus://`命令。
队列集成使用测试版官方客户端版本中的内部操作。未来的网易云音乐更新可能会重命名它们；使用`queue_control_ready`和返回的状态来诊断兼容性。
## 可选硬件伴侣
将此服务器与[Halo PixelBar MCP](https://github.com/Seraph310/halo-pixelbar-mcp)配对，以便MCP主机可以协调音乐与扬声器的环境光、像素屏幕和独立硬件音量。
## 相关项目
[luuu-h/netease-music-mcp](https://github.com/luuu-h/netease-music-mcp)启发了该项目，并提供了一种不同的、使用`neteasecli`、`mpv`、同步歌词和本地网页播放器的功能丰富的解决方案。当您想要独立的播放器UI时，请选择该项目；当您想要在不将cookie导入MCP的情况下继续使用官方Windows桌面端时，请选择此项目。
## 测试
```powershell
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
```
## 致谢
由Celia和OpenAI Codex共同开发。
Celia领导了产品方向和实时客户端验证。Codex协助了逆向工程、实现和测试。
## 许可证
[MIT](LICENSE)
