NetEase Music Local MCP

本地运行的网易云音乐 MCP：扫码登录、完整喜欢列表分页、歌曲元数据与推荐排重。由 MCP 客户端通过 stdio 启停，无需部署云服务。

本项目基于 Rainlxyl/netease-music-mcp-safe 继续改造，后者派生自 Vael-KY/netease-music-mcp。上游 MIT 版权声明完整保留；原上游介绍见 README.upstream.md。本项目与网易公司无隶属或背书关系。

这个版本增加了什么

这里保留的是上游歌单顺序，不能据此推断精确收藏时间或手动重排历史。snapshot_id 可帮助发现两次分页间的歌单变化。

Related MCP server: CloudmusicMCP

安装

需要 Python 3.13。Windows PowerShell：

git clone https://github.com/S4kuzy0/netease-music-local.git
Set-Location netease-music-local
py -V:3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-local.lock.txt

锁文件为 Windows 已验证依赖快照。其他平台或需要重新解析依赖时，使用 python -m pip install -r requirements-local.txt；不要将 Windows 专属 pywin32 锁文件直接用于 Linux。运行依赖 Pillow、PyCryptodome、qrcode 与 MCP SDK，无 GPU 或数据库服务要求。

连接 MCP 客户端

将客户端的 stdio 命令设为虚拟环境 Python 的绝对路径，参数设为 -B -u 加 local_mcp.py 的绝对路径。Codex 示例：

codex mcp add netease-music-local -- "<absolute-python-path>" -B -u "<absolute-local_mcp.py-path>"

环境变量 NETEASE_MCP_DATA_DIR 可指定独立本地状态目录。启动超时可设为 30 秒；大列表读取的工具超时可设为 180 秒。先核验 MCP 握手，再核验账号登录；只完成配置登记不代表工具已加载。

第一次使用

1. 调用 get_netease_login_status。

2. 如未登录，调用 start_netease_qr_login，在同一电脑打开返回的 login_url，用自己的网易云 App 扫码确认。遇到官方安全验证时由本人完成。

3. 调用 get_liked_songs(limit=100, offset=0)；每页最多 500 个位置。

4. 后续分页核对 snapshot_id、missing_song_ids 和计数。推荐前用 check_liked_song_ids 检查候选。

示例请求数据（由客户端调用相应工具）：

{"name":"get_liked_songs","arguments":{"limit":100,"offset":0}}

list_my_playlists、get_playlist_songs、搜索、歌曲详情、日推和播放记录等读取继续可用。本地 local_mcp.py 不暴露账号写入或退出登录工具，也不控制客户端播放。 上游 server.py 的托管 HTTP/OAuth 与写工具是另外一条运行入口，不属于本地 stdio 工具集；其说明保存在上游文档中。

数据与限制

.local/session.sqlite3 含登录态，只保留本机；真实 .env、日志、库导出和状态备份不应上传。临时登录链接十分钟失效，进程重启后未完成登录需重新开始。每位使用者运行自己的实例并登录自己的账号。

接口使用非官方网易云 Web API，可能变化、触发安全验证或受到账号权限限制。本项目不提供音频下载，不宣称听过歌曲，不自动推断曲风或收藏时间。登录细节、数据边界及终端客户端说明见 LOCAL.md，上游安全说明见 SECURITY.md。

开发与验证

.\.venv\Scripts\python.exe -m unittest discover -s tests -q
.\.venv\Scripts\python.exe -m pip check
.\.venv\Scripts\python.exe -u scripts/local_session.py

自动测试使用合成数据；真实账号验证需另行执行，不属于 CI。交互客户端可用 save_path 本地保存结果，该字段不是服务端工具参数。实现决策与历史验证见 项目记忆。

许可

MIT。上游版权声明与许可条件继续保留；本地代码的许可不授予音乐、账号或第三方平台内容的额外权利。