[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81117":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":13,"stars30d":16,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":17,"rankGlobal":10,"rankLanguage":10,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":10,"pushedAt":10,"updatedAt":23,"readmeContent":24,"aiSummary":25,"trendingCount":15,"starSnapshotCount":15,"syncStatus":26,"lastSyncTime":27,"discoverSource":28},81117,"netease-music-mcp","luuu-h\u002Fnetease-music-mcp","luuu-h","MCP-powered NetEase Cloud Music player: play music from NetEase Cloud Music via neteasecli and mpv, with a local synced-lyrics web player.","",null,"JavaScript",39,3,35,0,4,1.81,"MIT License",false,"main",true,[],"2026-06-12 02:04:11","# netease-music-mcp\n\n一个用于控制本机音乐播放的 MCP Server。它通过 `neteasecli` 和本地 `mpv` 播放音乐，并提供一个本地歌词播放器 Web UI。\n\n## 免责声明 \u002F Disclaimer\n\n本项目不是网易云音乐官方 MCP，也不隶属于、关联于或受网易云音乐官方认可。本项目仅用于个人学习、研究和本机自动化体验。使用时请合理遵守网易云音乐及相关服务的服务条款、版权规则和账号使用规范。\n\nThis project is not an official NetEase Cloud Music MCP and is not affiliated with, associated with, or endorsed by NetEase Cloud Music. It is intended for personal learning, research, and local automation experiments. Please use it responsibly and comply with the applicable NetEase Cloud Music terms of service, copyright rules, and account usage policies.\n\n你可以让 Claude Desktop 这类 MCP 客户端帮你：\n\n- 搜索并播放网易云音乐歌曲\n- 暂停、继续、停止、切歌\n- 打开本地 Web 播放器：`http:\u002F\u002F127.0.0.1:8765\u002F`\n- 显示歌词、歌单、喜欢的音乐和黑胶播放页\n- 在 AI 回复前读取当前歌曲、曲风、歌手和当前歌词上下文\n- 结束听歌时一键停止 `mpv` 并关闭本次 Web 播放器\n\n## 环境要求\n\n本项目目前主要面向 Windows 使用。\n\n| 依赖 | 要求 | 说明 |\n| --- | --- | --- |\n| Windows | 推荐 Windows 10\u002F11 | 当前主要在 Windows 上开发和测试 |\n| Node.js | 24 或更新版本 | `neteasecli` 当前版本自身要求 Node.js 24+ |\n| npm | 随 Node.js 安装 | 用于安装本项目依赖和全局 CLI |\n| 网易云音乐账号 | 可正常登录 | `neteasecli` 会从浏览器导入 Cookie |\n| `neteasecli` | 全局安装 | 用于访问网易云音乐账号、搜索、歌单和歌曲信息 |\n| `mpv` | 系统可执行文件 | 推荐加入系统 `PATH`，确保能运行 `mpv --version` |\n\n需要上游项目：[wangwalk\u002Fneteasecli](https:\u002F\u002Fgithub.com\u002Fwangwalk\u002Fneteasecli)。代码默认从 `%APPDATA%\\npm\\node_modules` 查找全局安装的 `neteasecli`。\n\n`mpv` 是前置依赖，需要提前安装，并确保在 PowerShell 里可以直接运行 `mpv --version`。\n\n`neteasecli` 和 `mpv` 都属于系统\u002F全局依赖，不会被 `npm install` 自动安装。\n`neteasecli` 当前版本自身要求 Node.js 24 或更新版本，因此推荐直接使用 Node.js 24+ 跑整个项目。\n如果你使用的是 Windows 便携版 `mpv.exe`，也可以临时放在项目根目录。\n\n## 安装\n\n克隆项目：\n\n```powershell\ngit clone https:\u002F\u002Fgithub.com\u002Fluuu-h\u002Fnetease-music-mcp.git\ncd netease-music-mcp\n```\n\n安装项目依赖：\n\n```powershell\nnpm install\n```\n\n全局安装音乐 CLI：\n\n```powershell\nnpm install -g neteasecli\n```\n\n先在浏览器里登录网易云音乐网页版。`neteasecli` 的登录方式是从浏览器导入 Cookie，不会在 MCP 里保存你的账号密码。\n\n```text\nhttps:\u002F\u002Fmusic.163.com\u002F\n```\n\n然后在 PowerShell 里导入登录状态：\n\n```powershell\nneteasecli auth login\n```\n\n如果你有多个 Chrome\u002FEdge 浏览器 Profile，可以指定 Profile：\n\n```powershell\nneteasecli auth login --profile \"Profile 1\"\n```\n\n确认登录状态：\n\n```powershell\nneteasecli --pretty auth check\n```\n\n安装 `mpv`。任选一种你常用的方式即可：\n\n```powershell\n# Chocolatey\nchoco install mpv -y\n\n# Scoop\nscoop install mpv\n```\n\n如果 PowerShell 提示找不到 `neteasecli` 命令，请确认 npm 全局命令目录已经加入 `PATH`。Windows 上通常是 `%APPDATA%\\npm`。\n\n## 检查安装\n\n语法检查：\n\n```powershell\nnpm run check\n```\n\nSmoke test：\n\n```powershell\nnpm run smoke\n```\n\n`smoke` 会检查：\n\n- 系统 `PATH` 或项目根目录里是否能找到 `mpv`\n- 是否全局安装了 `neteasecli`\n\n也可以在 MCP 客户端里让模型调用：\n\n```text\nnetease-music-mcp.check_environment\n```\n\n## 配置 Claude Desktop\n\nClaude Desktop 通过 `claude_desktop_config.json` 注册本地 MCP Server。配置完成后，Claude 才能看到 `netease-music-mcp` 这些工具。\n\n### 1. 确认项目绝对路径\n\n在项目目录里运行：\n\n```powershell\npwd\n```\n\n假设输出是：\n\n```text\nC:\\Users\\you\\projects\\netease-music-mcp\n```\n\n那么 MCP Server 文件路径就是：\n\n```text\nC:\\Users\\you\\projects\\netease-music-mcp\\src\\server.js\n```\n\n### 2. 打开 Claude Desktop 配置文件\n\n在 Windows 上打开 Claude Desktop 配置文件：\n\n```powershell\nnotepad \"$env:APPDATA\\Claude\\claude_desktop_config.json\"\n```\n\n如果提示找不到路径，先创建目录：\n\n```powershell\nNew-Item -ItemType Directory -Force \"$env:APPDATA\\Claude\"\nnotepad \"$env:APPDATA\\Claude\\claude_desktop_config.json\"\n```\n\n### 3. 写入 MCP 配置\n\n如果文件是空的，直接填入下面内容。注意把路径换成你自己的项目路径，并使用双反斜杠：\n\n```json\n{\n  \"mcpServers\": {\n    \"netease-music-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"C:\\\\path\\\\to\\\\netease-music-mcp\\\\src\\\\server.js\"\n      ]\n    }\n  }\n}\n```\n\n如果文件里已经有其他 MCP Server，就只把 `\"netease-music-mcp\"` 这一项加进已有的 `\"mcpServers\"` 里：\n\n```json\n{\n  \"mcpServers\": {\n    \"existing-server\": {\n      \"command\": \"...\"\n    },\n    \"netease-music-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"C:\\\\path\\\\to\\\\netease-music-mcp\\\\src\\\\server.js\"\n      ]\n    }\n  }\n}\n```\n\n### 4. 重启并验证\n\n保存配置后，完全退出并重新打开 Claude Desktop。\n\n然后在 Claude 里发送：\n\n```text\n请调用 netease-music-mcp.check_environment 检查我的本机音乐环境\n```\n\n如果返回里 `neteaseCliInstalled`、`mpvAvailable` 和登录状态都正常，就可以开始点歌。\n\n如果还没登录网易云，可以发送：\n\n```text\n请调用 netease-music-mcp.setup_netease_login 带我完成网易云登录\n```\n\n### 5. 常见配置错误\n\n- JSON 里 Windows 路径要写双反斜杠，例如 `C:\\\\path\\\\to\\\\file.js`\n- `args` 必须指向 `src\\\\server.js`，不是项目文件夹\n- 修改配置后必须重启 Claude Desktop\n- 如果 Claude 看不到工具，先确认 `node` 可以在 PowerShell 里直接运行：\n\n```powershell\nnode -v\n```\n\n## 单独启动 Web 播放器\n\n如果你想不通过 Claude，直接预览 Web UI：\n\n```powershell\nnode .\\src\\server.js --web-player --port 8765\n```\n\n然后在浏览器打开：\n\n```text\nhttp:\u002F\u002F127.0.0.1:8765\u002F\n```\n\nWeb 播放器包含：\n\n- 收藏歌单\n- 创建歌单\n- 我喜欢的音乐\n- 歌曲搜索\n- 歌单详情页\n- 底部播放器\n- 播放队列\n- 黑胶歌词播放页\n- CLI 支持时显示双语歌词\n\n## MCP 工具列表\n\n| 工具名 | 作用 |\n| --- | --- |\n| `check_environment` | 检查 `neteasecli`、`mpv` 和登录状态 |\n| `setup_netease_login` | 引导用户安装\u002F登录 `neteasecli`，并返回下一步命令 |\n| `search_song` | 搜索网易云歌曲 |\n| `play_song` | 按关键词搜索并播放最匹配的歌曲 |\n| `play_track` | 按网易云歌曲 ID 播放 |\n| `next_song` | 搜索并切换到另一首歌 |\n| `pause` | 暂停播放 |\n| `resume` | 继续播放 |\n| `stop` | 停止播放并清理当前听歌状态 |\n| `shutdown` | 结束本次听歌会话：停止播放、停止 `mpv`、清理状态，并关闭本次 Web 播放器，但保留 MCP 工具进程 |\n| `get_status` | 获取播放器状态和缓存的歌曲信息 |\n| `get_listening_context` | 获取当前歌曲、曲风、歌手和歌词上下文 |\n| `open_web_player` | 启动本地 Web 播放器并返回 localhost URL |\n\n## 推荐 Claude 指令\n\n建议把下面这段放进 Claude 的项目指令或自定义指令里：\n\n```text\n你可以使用 netease-music-mcp MCP 控制本机音乐。\n\n当用户要配置、登录、安装、修复或检查 neteasecli 时，调用 netease-music-mcp.setup_netease_login，并按工具返回的 steps 带用户完成登录。用户执行完命令后，再调用一次 netease-music-mcp.setup_netease_login 或 netease-music-mcp.check_environment 验证。\n\n当用户第一次要求播放音乐、点歌、听歌、打开播放器、查看歌词播放器，或当前对话还没有打开过播放器界面时，你必须先调用 netease-music-mcp.open_web_player，并把返回的 localhost URL 告诉用户。\n\n当用户要求播放音乐时，调用 netease-music-mcp.play_song 或 netease-music-mcp.play_track。\n当用户要求切歌时，调用 netease-music-mcp.next_song。\n当用户要求暂停、继续、停止时，调用 netease-music-mcp.pause、netease-music-mcp.resume、netease-music-mcp.stop。\n\n音乐播放期间，每次回复用户前，都必须先调用 netease-music-mcp.get_listening_context。\n把返回的 ai_context 当作当前对话上下文使用。\n\n点歌或切歌成功后，也要使用工具返回的 ai_context。\nplayback.style 字段已经优先来自网易云歌曲百科，可直接作为曲风\u002F风格使用。\n\n如果 netease-music-mcp.open_web_player 已经返回过 URL，不要重复打开，除非用户明确要求重新打开播放器。\n如果用户问播放器在哪里，直接给出上次的 URL；如果不知道 URL，再调用 netease-music-mcp.open_web_player。\n\n当用户说“结束听歌”、“不听了”、“关闭播放器”、“停止整个程序”，或任何表示要结束音乐\u002F听歌会话的请求时，调用 netease-music-mcp.shutdown。这个工具只结束本次听歌和 Web 播放器，不会关闭 MCP 工具进程，因此之后仍然可以继续调用 netease-music-mcp。\n```\n\n## 使用示例\n\n在 Claude Desktop 里可以这样说：\n\n```text\n一起听歌吧，听歌过程中每次回复我之前请先看 listening_context\n打开音乐播放器\n播放 布拉格广场 蔡依林\n切到 编号89757 林俊杰\n暂停\n继续\n结束听歌\n```\n\n## 听歌上下文是怎么工作的\n\n每次开始播放歌曲后，服务会把当前歌曲信息缓存到 `.listening-state.json`：\n\n- 歌曲 ID\n- 歌名\n- 歌手\n- 专辑\n- 封面 URL\n- 歌曲时长\n- 曲风，优先来自网易云歌曲百科\n- 带时间戳的歌词\n- CLI 提供时的翻译歌词\n\n`get_listening_context` 会返回类似下面的 `ai_context`，其中歌词是当前播放时间之后的 6 句：\n\n```text\n我们正在一起听歌，你现在跟我一起听xxx，曲风是xxx，歌手是xxx，当前的6句歌词是xxx\n```\n\n注意：MCP Server 本身不能 100% 强制 Claude 在每次回复前调用某个工具。上面的推荐指令会强约束 Claude 主动调用 `get_listening_context`。如果你需要硬性保证，需要自己做一个代理层或自定义客户端，在每次发给模型前自动注入听歌上下文。\n\n## 常见问题\n\n### Claude 看不到工具\n\n修改 `claude_desktop_config.json` 后需要重启 Claude Desktop。\n\n同时确认配置里的 `src\u002Fserver.js` 是正确的绝对路径。\n\n### PowerShell 找不到 `neteasecli`\n\n先确认安装：\n\n```powershell\nnpm install -g neteasecli\n```\n\n然后确认 npm 全局命令目录在 `PATH` 里。Windows 通常需要包含：\n\n```text\n%APPDATA%\\npm\n```\n\n如果命令暂时不可用，也可以直接用 Node 运行全局安装的 CLI：\n\n```powershell\nnode \"$env:APPDATA\\npm\\node_modules\\neteasecli\\dist\\index.js\" auth login\nnode \"$env:APPDATA\\npm\\node_modules\\neteasecli\\dist\\index.js\" --pretty auth check\n```\n\n### 如何登录网易云\n\n`neteasecli` 不走短信验证码登录，而是从浏览器导入网易云音乐 Cookie：\n\n1. 先在 Chrome 或 Edge 里打开 `https:\u002F\u002Fmusic.163.com\u002F` 并登录网易云账号。\n2. 回到 PowerShell 运行：\n\n```powershell\nneteasecli auth login\n```\n\n3. 检查登录状态：\n\n```powershell\nneteasecli --pretty auth check\n```\n\n你也可以直接让 Claude 调用：\n\n```text\nnetease-music-mcp.setup_netease_login\n```\n\n它会检查当前缺哪一步，并返回下一步应该运行的命令。\n\n### neteasecli 找不到登录 Cookies\n\n如果 `neteasecli auth login` 一直找不到浏览器里的登录 Cookies，可以手动写入 `neteasecli` 的 session 文件。这通常比继续处理浏览器锁文件更直接。\n\n默认 profile 的 session 文件路径是：\n\n```text\nC:\\Users\\\u003C你的用户名>\\.config\\neteasecli\\profiles\\default\\session.json\n```\n\n文件内容最少只需要 `MUSIC_U`：\n\n```json\n{\"MUSIC_U\":\"这里填你从浏览器里拿到的值\"}\n```\n\n获取 `MUSIC_U` 的方法：\n\n1. 在 Edge、Chrome 或其他浏览器里打开 `https:\u002F\u002Fmusic.163.com\u002F` 并登录。\n2. 按 `F12` 打开开发者工具。\n3. 进入 `Application` \u002F `应用程序`。\n4. 在左侧找到 `Cookies` -> `https:\u002F\u002Fmusic.163.com`。\n5. 找到名为 `MUSIC_U` 的 Cookie，复制它的 `Value`。\n\n然后在 PowerShell 里执行：\n\n```powershell\nNew-Item -ItemType Directory -Force \"$HOME\\.config\\neteasecli\\profiles\\default\"\nSet-Content -Encoding UTF8 \"$HOME\\.config\\neteasecli\\profiles\\default\\session.json\" '{\"MUSIC_U\":\"把这里替换成你的MUSIC_U\"}'\nneteasecli --pretty auth check\n```\n\n### Smoke test 提示找不到 `mpv`\n\n先确认 PowerShell 里能直接运行：\n\n```powershell\nmpv --version\n```\n\n如果不能，请先安装 `mpv`，或者把 `mpv.exe` 所在目录加入系统 `PATH`。如果你只是本机开发，也可以把便携版 `mpv.exe` 放在项目根目录；项目里的 `.gitignore` 已经忽略了本机 mpv 二进制和 DLL，避免误上传到 GitHub。\n\n### 关闭网页后音乐还在播放\n\n网页只是播放器界面，真正播放音频的是后台 `mpv`。\n\n只停止播放：\n\n```text\nnetease-music-mcp.stop\n```\n\n结束整个听歌会话并关闭本次 Web 播放器：\n\n```text\nnetease-music-mcp.shutdown\n```\n\n### 手动停止后台 mpv\n\n如果你想手动停掉后台播放进程，可以在 Windows PowerShell 里运行：\n\n```powershell\nGet-Process mpv,mpv.com -ErrorAction SilentlyContinue | Stop-Process -Force\n```\n\n## 开发\n\n先进入项目目录：\n\n```powershell\ncd netease-music-mcp\n```\n\n运行检查：\n\n```powershell\nnpm run check\nnpm run smoke\n```\n\n启动 Web UI：\n\n```powershell\nnode .\\src\\server.js --web-player --port 8765\n```\n\n启动 MCP Server：\n\n```powershell\nnpm start\n```\n\n","该项目是一个基于MCP的网易云音乐播放器，通过neteasecli和mpv在本地播放网易云音乐，并提供同步歌词的Web界面。核心功能包括搜索并播放歌曲、控制播放（暂停、继续、停止、切歌）、显示歌词及歌单等。技术上依赖于JavaScript实现，要求Node.js 24+环境以及全局安装的neteasecli和mpv。适合需要在Windows环境下进行个性化音乐播放体验的用户使用，尤其是对自动化操作有一定需求的人群。请注意，此项目仅供个人学习研究之用，需遵守相关服务条款与版权规则。",2,"2026-06-11 04:03:35","CREATED_QUERY"]