Orpheus · 网易云 Agent 点歌桥

让 Hermes / Codex / 任意支持 MCP 的 Agent 用自然语言控制本机网易云音乐的播放：点歌、放歌单、查待播队列、暂停/切歌/音量。

插件跑在网易云里（负责真正操作播放器），Agent 只负责理解你的话和选歌，两者通过本机的一个小服务连接。

你: "放一首 Novo Amor"  →  Agent(MCP)  →  本机桥接服务(127.0.0.1:17632)  →  BetterNCM 插件  →  网易云播放器
                                              ↑ 配对令牌鉴权 / 结果回传

命名彩蛋：网易云自己的内部协议就叫 orpheus://，而俄耳甫斯（Orpheus）是希腊神话中的音乐之神。

目录结构

orpheus/
├── src/
│   ├── server.js         本地 HTTP + WebSocket 桥接服务（Agent ←→ 插件的中间层）
│   ├── mcp.js            MCP stdio 服务器：把 19 个工具暴露给 Agent
│   ├── tools.js          工具定义 + zod 参数校验（唯一可信的参数边界）
│   ├── client.js         内部：MCP → 桥接服务的 HTTP 客户端
│   ├── ensure-service.js 内部：MCP 启动时自动拉起桥接服务
│   ├── config.js         读写 .local/config.json（端口 + 配对令牌）
│   ├── cli.js            命令行调用单个工具（调试用）
│   └── install.js        把插件安装进 BetterNCM
├── plugin/
│   ├── manifest.json     BetterNCM 插件清单（name: Orpheus, slug: orpheus）
│   └── main.js           插件运行时：运行时探测网易云接口、执行命令、回报结果
└── test/                 单元测试（node --test）

Related MCP server: mcp_music_server

前置条件

• Node.js ≥ 20

• 网易云音乐 PC 版 3.1.20 ~ 3.x（已在 3.1.41 上实测）

• BetterNCM ≥ 1.3.4（已装好并注入）

• 网易云已登录账号（歌单、权限相关操作需要）

安装

1. 安装依赖

cd outputs/orpheus
npm install

2. 把插件装进 BetterNCM（会自动生成本机配对令牌）

# 参数是 BetterNCM 的数据目录，默认 C:/betterncm
node src/install.js C:/betterncm

它会把 plugin/ 复制到 C:/betterncm/plugins_dev/orpheus/，并写入 connection.json（内含本机 ws://127.0.0.1:<port>/plugin 和配对令牌）。然后重启网易云让插件加载（BetterNCM 不热重载）。

3. 起桥接服务（一般不用手动起——MCP 启动时会自动拉起来）

npm start        # 手动启动，监听 127.0.0.1:17632

健康检查：curl -H "Authorization: Bearer <token>" http://127.0.0.1:17632/health

接入 Agent

Hermes

printf 'y\n' | hermes mcp add orpheus \
  --command "C:/Program Files/nodejs/node.exe" \
  --args "<绝对路径>/orpheus/src/mcp.js" \
  --connect-timeout 30

hermes mcp add 会问 "Enable all 19 tools? [Y/n]"，非交互环境会被取消，所以用 printf 'y\n' | 喂答案。

Codex

在 ~/.codex/config.toml 追加：

[mcp_servers.orpheus]
command = 'C:\Program Files\nodejs\node.exe'
args = ['<绝对路径>\orpheus\src\mcp.js']
startup_timeout_sec = 60

其他 MCP 客户端

按标准 stdio 服务器配置：命令 = node，参数 = src/mcp.js 的绝对路径。

工具（19 个）

安全设计

• 桥接服务只监听 127.0.0.1，不对外网开放

• 插件→服务、Agent→服务 都用配对令牌鉴权（常量时间比较）

• 拒绝带 Origin 的请求（防浏览器页面调用），阻塞无关的跨站请求

• 不暴露任何"执行任意代码"的工具，参数由 zod 白名单校验（歌曲 ID 必须是数字等）

• 不导出账号 Cookie，不调用第三方音乐 API，全部走网易云客户端自身的接口

已知行为与限制

• 点歌确认机制：只有客户端回读确认目标状态才返回 verified:true。屏蔽接口目前仅能确认请求被接受，返回 accepted:true, verified:false；喜欢操作未回读到目标状态也会明确返回 verified:false。超时返回 TIMEOUT，不要自动重试写操作

• 无版权/VIP 不可播的歌返回 UNPLAYABLE，不会假装成功

• play_playlist 会替换当前待播队列（不可逆），且受 1000 首上限约束

• next / previous 走网易云内部 dispatch（playingList/jump2Track；FM 模式走 fmPlaying/playNext|playPre），不依赖易碎的 DOM 选择器

• volume 通过原生音频接口设置

• 队列结构若与预期不符会明确报 UNSUPPORTED_QUEUE，而不是静默返回错误数据

测试

npm test        # 鉴权、异常消息、超时并发、云端写操作模拟、时长、真实 MCP 握手

0.1.1 可靠性与性能改进

• 异常 WebSocket 消息只关闭对应连接，不再导致桥接服务退出。

• 请求超时后保持执行锁，直到原命令结束或插件断线；避免超时后并行写入。若接口一直挂起，后续命令返回 BUSY，需要等待或重启网易云。

• 每次云端写入前检查截止时间，不自动换参数重试。已经发出的网易云请求无法撤回，超时仍可能意味着操作已执行但未确认。

• 歌单增删使用完整列表验证；无效响应、缺失数据、截断列表均不算成功。创建歌单只按返回的新 ID 验证；删除歌单逐页核对。

• ids: [] 明确报错；省略 ids 仍表示当前歌曲。账号歌单查询按页读取、去重后返回指定范围，兼容接口额外附带的置顶或创建歌单。

• 播放状态 durationMs 统一为毫秒，增加 pluginVersion 便于确认加载版本。

• API 函数按需解析并缓存，歌单读取绕过客户端结果缓存；找到所需模块即停止扫描；批量歌曲比对使用 Set；文档隐藏时跳过面板刷新，主题检测最多每 5 秒一次。

• 工具清单由 src/tools.js 生成到插件，安装时自动同步；开发时运行 npm run sync-tools。测试会检测清单漂移。

升级后需重启网易云以加载新版插件，并重启本地桥接服务；不会改变账号登录配置或配对令牌。测试使用模拟云端接口，不修改真实歌单。以上改动减少了重复扫描和比对工作，但尚未测量真实客户端 CPU/内存变化。

故障排查

本项目通过运行时探测网易云 3.x 的 webpack 模块来定位其内部接口（搜索、歌曲详情、歌单、播放派发等），因此对客户端小版本更新有一定耐受性；但网易云改版仍可能导致接口失效，此时对应工具会明确报错而非静默失败。

许可证

MIT © 2026 SUPERtongmeng

仅供个人学习与自用。使用时请遵守网易云音乐的服务条款，不要用于传播版权内容或账号共享。