Skip to main content
Glama
netease-music-mcp
by xinyu68

网易云音乐 MCP 与 Codex 插件

用自己的网易云账号,在 Codex 中点歌,让电脑播放音乐。一个项目,两种入口:独立 MCP 和本地 Codex 插件。 不需要 ESP32、其他外接设备或网易云桌面客户端。

当前版本 0.6.2,源代码使用 MIT 许可证。插件包含音乐 Skill 和 MCP 配置,播放核心只有一份。音频由独立 mpv 播放器获取和解码,不经过语言模型;声音输出到电脑当前扬声器或耳机。

0.6.2 修正取音源请求的客户端标识不一致:保留依赖原有 PC 参数,使 User-Agent 与之匹配。Mac 上《十年》已完成一次实际播放与暂停验证,服务端偶发拒绝是否完全消失仍待使用观察。更新后需重新加载使用插件的聊天,已运行的旧 MCP 进程不会热替换。详见本机验收记录。

可以做什么

  • 同时查找喜欢列表和公开曲库,区分精确版本、翻唱与缺失歌手的收藏候选,再播放指定歌曲

  • 播放“我喜欢的音乐”或指定歌单,顺序切歌

  • 播放每日推荐、网易云热歌榜;开启心动模式并自动补充智能推荐队列

  • 根据明确指令喜欢或取消喜欢歌曲,写入后读回确认

  • 暂停、继续、停止、上一首、下一首、定位与独立音量;记住明确设置的音量,重启或升级后自动恢复

  • 顺序播放、随机播放、单曲循环;切换模式保留歌曲、进度及暂停状态

  • 查询实际播放状态、读取歌单和带时间戳歌词

  • 用自己的账号及会员权限播放;不会解锁无权播放的歌曲

可以直接说:“播放我喜欢的音乐”“播放陈奕迅的十年”“下一首”“暂停一下”“音量调到二十”。当前没有独立播放器图形界面。

也可以说:“开启心动模式”“播放今天的每日推荐”“播放热歌榜”“喜欢这首歌”“取消喜欢这首歌”。心动模式默认需要喜欢列表中已有歌曲;普通点歌、播放其他列表或停止会退出心动模式。

“随机播放我喜欢的音乐”可以一次调用完成,从整个列表随机选第一首,再按打乱后的顺序播放,每轮列表内不重复抽选,播完结束。“单曲循环这首歌”只改变自然曲尾行为,手动上一首/下一首仍会切歌;“恢复顺序播放”可退出。模式在本次 MCP 进程内保留,换歌单和停止不会重置,重启服务后默认为顺序播放。心动推荐来源与播放模式独立,随机心动在当前批次播完后继续补充。

Related MCP server: Spotify MCP

查找收藏中的歌曲

点歌会同时查喜欢列表和公开曲库;即使公开搜索只有翻唱,也能定位收藏中的独立歌曲 ID。已知歌手单独传 artist,明确找收藏时传 source: liked。缺失歌手只标为未知候选,不冒充已匹配原唱。某个 ID 无权限不代表同名收藏版本也无权限。

netease_search 的返回值从数组改为 { candidates, sources },客户端需读取 candidates 并检查来源状态。详见 MCP 工具说明。

平台与准备

平台

状态

首次准备

Windows x64

已做本机实际验收

Node.js >=22.13;Edge WebView2 Runtime(多数电脑已有)

macOS Apple Silicon / Intel

已验证收藏检索;完整安装和播放验收待补

Node.js >=22.13;Xcode Command Line Tools;已有 mpv,或已有 Homebrew 供脚本安装 mpv

Linux / Windows ARM64

暂不提供完整首次登录安装流程

不作为当前开箱即用平台承诺

Codex 插件需要支持本地插件的桌面/CLI。自动注册需要终端能执行 codex plugin;当前用 Codex CLI 0.153.4 验证。只有 Codex 桌面而没有 CLI 时,也可在项目中准备后从本地插件源手动安装。网页版或云端会话不能直接让这台电脑发声。

安装 Node.js 后,重新打开终端。下载本项目源码 ZIP 并解压,或克隆仓库,再进入项目目录。下载 ZIP 使用时不要求安装 Git;API 依赖固定为 HTTPS 源码包并由 lockfile 校验。

源码仓库:xinyu68/netease-music-mcp。可以下载 源码 ZIP,或使用 Git:

git clone https://github.com/xinyu68/netease-music-mcp.git
cd netease-music-mcp

推荐:在 Codex 中作为插件使用

在项目根目录执行:

node scripts/setup.mjs --plugin --install-plugin

这一条命令依次完成:检查环境 → 在用户目录准备固定依赖 → 安装播放器/编译登录窗口 → 必要时打开官方网页登录 → 在线检查账号 → 构建并注册本地 Codex 插件。

登录由你本人在官方页面完成,不需要把 Cookie 发给 Codex。准备完成后重新打开 Codex 聊天,选择“网易云音乐”插件,直接点歌即可。

不希望脚本注册插件、或者没有 codex 命令时:

node scripts/setup.mjs --plugin

然后使用项目的本地插件源安装;详细步骤见 安装与使用。插件正常启动不下载依赖、不打开登录窗口,只加载已经准备好的本地运行目录。

也可以只使用独立 MCP

在项目根目录执行:

node scripts/setup.mjs

准备完成后,以 stdio 启动 node /项目绝对路径/src/server.mjs。在 Codex 或其他兼容 MCP 客户端配置该入口。生成本机路径的 TOML 示例:

node scripts/print-mcp-config.mjs

只复制输出的配置,不需要手动常驻一个终端。独立入口支持相同的 25 个工具,不要求安装 Codex 插件。插件和独立 MCP 二选一启用,避免同一个客户端启动两份播放实例。示例见 examples/codex-mcp.toml。

首次登录、升级与配置

  • 插件的依赖和播放器存放于用户状态目录的 runtimes/<版本-源码指纹>/;Codex 插件缓存中只放源码,更新插件时不会把登录凭据打包进去

  • Windows 状态目录:%LOCALAPPDATA%\netease-music-mcp,会话用当前用户 DPAPI 加密

  • Mac 状态目录:~/.local/state/netease-music-mcp,当前会话为 Base64 加 0600 权限,不是加密存储;Mac 登录仍须实机验收

  • 下载新版本后重新执行相同的 setup 命令。有效会话会复用,旧版本运行目录保留;新依赖准备失败不会覆盖旧版本

  • --no-login 只准备依赖;--check 只检查前置条件,不安装、不登录

  • 可设置 NETEASE_MUSIC_STATE_DIR 指定状态目录;必须在 setup 和实际 MCP/Codex 进程中保持相同环境值

  • 高级设置参考 config.example.json;NETEASE_MCP_CONFIG 可指定不含凭据的本机配置文件,插件启动和准备阶段应使用同一配置

完整说明见 登录与凭据、安装与使用 和 MCP 工具说明。

开发与验证

源码开发安装完整依赖(普通用户无需执行此节):

npm ci --ignore-scripts
npm run check
npm run plugin:build

命令

用途

node scripts/setup.mjs --help

查看首次准备选项,执行前不依赖 node_modules

npm run check

格式、语法和离线回归

npm run verify

实际账号、全部工具及播放验收;会发声,最后停止

npm run verify:plugin -- --online

在隔离 Codex 配置中安装插件,从真实缓存入口验证工具和账号;不修改你原来的 Codex 配置

npm run bundle

生成源码包和本地插件包,均不含个人凭据或依赖二进制

0.4.0 的 Windows 独立播放验收已调用验证 24 个工具,会员曲目实际连续播放超过 32 秒。日推、心动模式、热歌榜已实际播放;收藏的真实账号验收使用已符合目标的状态,不为测试主动更改收藏。0.5.0 的 61 项离线测试及安装后 25 工具发现、播放模式切换检查通过;新增模式的真实音频曲尾实播尚未验收。0.6.0 在 macOS 通过 74 项离线测试和当前账号的只读收藏检索,未运行新版真实音频全工具验收。详见 本机验收记录。远端 CI 结果以对应提交的 Actions 为准。

边界与常见问题

  • 需要联网访问网易云、歌曲 CDN;首次准备还需访问 npm、GitHub 和微软 NuGet

  • 会员状态、能搜到歌曲、能看到歌词,都不代表该曲目有完整播放权限;试听/无权/不支持的保护资源会明确报错

  • 非官方 API 可能随平台变化;不保证全部地区、账号和曲库都能播放

  • 本项目不提供歌曲下载、会员解锁、自定义歌单编辑或修改系统音频路由

  • 当前不需要也不包含 ESP32 输出适配;硬件集成属于其他项目,不影响电脑独立使用

  • MPV_NOT_FOUND、LOGIN_REQUIRED、API_TIMEOUT 等排障见安装指南;不要将会话文件、Cookie 或音源地址发到 Issue

本项目通过 GitHub 分发开源源码和本地插件构建流程,尚未发布 npm 或上架官方插件目录。公开源码分发和官方目录上架是不同流程。

参与开发

阅读 CONTRIBUTING.md、架构与维护、CHANGELOG.md 和 第三方说明。问题反馈请提供系统、Node/Codex 版本和脱敏错误码,使用你自己的网易云账号。

Available Tools

25 tools
netease_account_statusA
Read-only

验证网易云登录及会员状态,不返回凭据

Inputs: no named parameters.

netease_launchB

准备独立播放引擎,不启动网易云桌面客户端

Inputs: no named parameters.

netease_likeA

按明确意图喜欢或取消喜欢歌曲;liked为true/false,省略songId时使用当前歌曲,写入后读回验证

Inputs: liked (required), requestId (required), songId.

netease_liked_songsC
Read-only

分页读取我喜欢的音乐

Inputs: limit, offset.

netease_lyricsB
Read-only

读取用于显示的带时间戳歌词;不是播放状态

Inputs: songId (required).

netease_nextC

播放队列下一首

Inputs: requestId (required).

netease_pauseB

确保暂停,保留当前位置,重复暂停不会反向播放

Inputs: requestId (required).

netease_playC

直接取流播放明确歌曲ID并验证真实进度

Inputs: songId (required), requestId (required), mode, level.

netease_play_dailyC

播放账号今天的每日推荐歌曲

Inputs: requestId (required), mode.

netease_play_heart_modeB

开启网易云心动模式;默认基于我喜欢的音乐,队列结束自动获取下一批推荐

Inputs: requestId (required), mode, count, playlistId, +1 more.

netease_play_hot_chartA

识别并播放网易云热歌榜,不替换为其他榜单

Inputs: requestId (required), mode.

netease_play_likedC

建立我喜欢的音乐队列并开始播放

Inputs: requestId (required), mode.

netease_playlistsB
Read-only

读取当前账号的歌单摘要

Inputs: no named parameters.

netease_playlist_tracksC
Read-only

分页读取歌单歌曲

Inputs: playlistId (required), limit, offset.

netease_play_modeA

切换顺序、随机或单曲循环,保留当前歌曲、进度和暂停状态;随机队列每首一次,单曲循环不阻止手动切歌

Inputs: mode (required), requestId (required).

netease_play_playlistC

建立指定歌单队列并开始播放

Inputs: requestId (required), playlistId (required), mode.

netease_previousC

播放队列上一首

Inputs: requestId (required).

netease_queueA
Read-only

读取当前队列摘要及当前位置之后至多五首ID

Inputs: no named parameters.

netease_resumeB

继续当前歌曲,必要时刷新已过期的音频地址

Inputs: requestId (required).

netease_seekB

定位到歌曲中的秒数;暂停状态定位后仍保持暂停

Inputs: seconds (required), requestId (required).

netease_song_detailB
Read-only

读取歌曲信息和歌词,详情可见不代表具有播放权限

Inputs: songId (required).

netease_statusA
Read-only

读取独立播放器真实位置和状态,verified=false时不可报告已播放

Inputs: no named parameters.

netease_stopA

立即停止并卸载音频、归零进度,保留队列;会取消尚未完成的点歌

Inputs: requestId (required).

netease_volumeA

按用户明确目标设置播放器音量0到100,成功后保存供重启或升级恢复;不改变系统主音量,保存失败会明确报错

Inputs: volume (required), requestId (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 25 tools

    Disambiguation4/5

    Most tools have clearly distinct playback, library, account, or search purposes. Some overlap remains between generic playback and source-specific play tools, and between netease_song_detail and netease_lyrics, but descriptions generally resolve these boundaries.

    Naming Consistency5/5

    All tools consistently use the netease_ prefix followed by snake_case names. Although some names are verb-led and others noun-led, the overall convention is predictable and easy to scan.

    Tool Count3/5

    At 25 tools, the surface is at the heavy end for a music playback server. Several source-specific play tools could likely be consolidated, though each control still has a plausible role.

    Completeness4/5

    Core playback, queue navigation, search, lyrics, account status, and library browsing are well covered. Minor gaps exist around queue modification and playlist management, but the main agent workflows are supported.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers