netease-music-mcp

An MCP Server for controlling local music playback. It plays music via neteasecli and local mpv, and provides a local lyrics player Web UI.

免责声明 / Disclaimer

本项目不是网易云音乐官方 MCP，也不隶属于、关联于或受网易云音乐官方认可。本项目仅用于个人学习、研究和本机自动化体验。使用时请合理遵守网易云音乐及相关服务的服务条款、版权规则和账号使用规范。

This 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.

You can let MCP clients like Claude Desktop help you:

• Search and play NetEase Cloud Music songs

• Pause, resume, stop, and skip tracks

• Open the local web player: http://127.0.0.1:8765/

• Display lyrics, playlists, liked music, and the vinyl playback page

• Read the current song, genre, artist, and current lyrics context before AI responses

• Stop mpv and close the web player with one click when finished listening

Related MCP server: mcp_music_server

Environment Requirements

This project is currently primarily aimed at Windows users.

Requires upstream project: wangwalk/neteasecli. The code looks for the globally installed neteasecli in %APPDATA%\npm\node_modules by default.

mpv is a prerequisite dependency; it must be installed beforehand, and you must ensure mpv --version can be run directly in PowerShell.

Both neteasecli and mpv are system/global dependencies and will not be automatically installed by npm install. The current version of neteasecli requires Node.js 24 or newer, so it is recommended to use Node.js 24+ to run the entire project. If you are using the Windows portable version of mpv.exe, you can also temporarily place it in the project root directory.

Installation

Clone the project:

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

Install project dependencies:

npm install

Globally install the music CLI:

npm install -g neteasecli

First, log in to the NetEase Cloud Music web version in your browser. neteasecli logs in by importing cookies from the browser and does not save your account password in the MCP.

https://music.163.com/

Then import the login status in PowerShell:

neteasecli auth login

If you have multiple Chrome/Edge browser profiles, you can specify the profile:

neteasecli auth login --profile "Profile 1"

Verify login status:

neteasecli --pretty auth check

Install mpv. Choose any method you are comfortable with:

# Chocolatey
choco install mpv -y

# Scoop
scoop install mpv

If PowerShell reports that the neteasecli command cannot be found, please ensure that the npm global command directory has been added to your PATH. On Windows, this is usually %APPDATA%\npm.

Verify Installation

Syntax check:

npm run check

Smoke test:

npm run smoke

smoke will check:

• Whether mpv can be found in the system PATH or project root directory

• Whether neteasecli is installed globally

You can also ask the model to call it in the MCP client:

netease-music-mcp.check_environment

Configure Claude Desktop

Claude Desktop registers local MCP Servers via claude_desktop_config.json. Once configured, Claude will be able to see tools like netease-music-mcp.

1. Confirm the absolute path of the project

Run in the project directory:

pwd

Assuming the output is:

C:\Users\you\projects\netease-music-mcp

Then the MCP Server file path is:

C:\Users\you\projects\netease-music-mcp\src\server.js

2. Open the Claude Desktop configuration file

Open the Claude Desktop configuration file on Windows:

notepad "$env:APPDATA\Claude\claude_desktop_config.json"

If it says the path cannot be found, create the directory first:

New-Item -ItemType Directory -Force "$env:APPDATA\Claude"
notepad "$env:APPDATA\Claude\claude_desktop_config.json"

3. Write the MCP configuration

If the file is empty, paste the following content directly. Note: replace the path with your own project path and use double backslashes:

{
  "mcpServers": {
    "netease-music-mcp": {
      "command": "node",
      "args": [
        "C:\\path\\to\\netease-music-mcp\\src\\server.js"
      ]
    }
  }
}

If the file already contains other MCP Servers, only add the "netease-music-mcp" entry into the existing "mcpServers" block:

{
  "mcpServers": {
    "existing-server": {
      "command": "..."
    },
    "netease-music-mcp": {
      "command": "node",
      "args": [
        "C:\\path\\to\\netease-music-mcp\\src\\server.js"
      ]
    }
  }
}

4. Restart and verify

After saving the configuration, completely exit and reopen Claude Desktop.

Then send the following in Claude:

请调用 netease-music-mcp.check_environment 检查我的本机音乐环境

If the response shows neteaseCliInstalled, mpvAvailable, and the login status are all normal, you can start requesting songs.

If you haven't logged in to NetEase Cloud yet, you can send:

请调用 netease-music-mcp.setup_netease_login 带我完成网易云登录

5. Common configuration errors

• Windows paths in JSON must use double backslashes, e.g., C:\\path\\to\\file.js

• args must point to src\\server.js, not the project folder

• You must restart Claude Desktop after modifying the configuration

• If Claude cannot see the tools, first confirm that node can be run directly in PowerShell:

node -v

Start the Web Player Separately

If you want to preview the Web UI without using Claude:

node .\src\server.js --web-player --port 8765

Then open in your browser:

http://127.0.0.1:8765/

The web player includes:

• Favorite playlists

• Create playlists

• My liked music

• Song search

• Playlist details page

• Bottom player

• Play queue

• Vinyl lyrics playback page

• Bilingual lyrics display when supported by CLI

MCP Tool List

Recommended Claude Instructions

It is recommended to add the following section to Claude's project instructions or custom instructions:

你可以使用 netease-music-mcp MCP 控制本机音乐。

当用户要配置、登录、安装、修复或检查 neteasecli 时，调用 netease-music-mcp.setup_netease_login，并按工具返回的 steps 带用户完成登录。用户执行完命令后，再调用一次 netease-music-mcp.setup_netease_login 或 netease-music-mcp.check_environment 验证。

当用户第一次要求播放音乐、点歌、听歌、打开播放器、查看歌词播放器，或当前对话还没有打开过播放器界面时，你必须先调用 netease-music-mcp.open_web_player，并把返回的 localhost URL 告诉用户。

当用户要求播放音乐时，调用 netease-music-mcp.play_song 或 netease-music-mcp.play_track。
当用户要求切歌时，调用 netease-music-mcp.next_song。
当用户要求暂停、继续、停止时，调用 netease-music-mcp.pause、netease-music-mcp.resume、netease-music-mcp.stop。

音乐播放期间，每次回复用户前，都必须先调用 netease-music-mcp.get_listening_context。
把返回的 ai_context 当作当前对话上下文使用。

点歌或切歌成功后，也要使用工具返回的 ai_context。
playback.style 字段已经优先来自网易云歌曲百科，可直接作为曲风/风格使用。

如果 netease-music-mcp.open_web_player 已经返回过 URL，不要重复打开，除非用户明确要求重新打开播放器。
如果用户问播放器在哪里，直接给出上次的 URL；如果不知道 URL，再调用 netease-music-mcp.open_web_player。

当用户说“结束听歌”、“不听了”、“关闭播放器”、“停止整个程序”，或任何表示要结束音乐/听歌会话的请求时，调用 netease-music-mcp.shutdown。这个工具只结束本次听歌和 Web 播放器，不会关闭 MCP 工具进程，因此之后仍然可以继续调用 netease-music-mcp。

Usage Example

In Claude Desktop, you can say:

一起听歌吧，听歌过程中每次回复我之前请先看 listening_context
打开音乐播放器
播放 布拉格广场 蔡依林
切到 编号89757 林俊杰
暂停
继续
结束听歌

How Listening Context Works

Every time a song starts playing, the service caches the current song information to .listening-state.json:

• Song ID

• Song title

• Artist

• Album

• Cover URL

• Song duration

• Genre (prioritized from NetEase Cloud song encyclopedia)

• Timestamped lyrics

• Translated lyrics when provided by the CLI

get_listening_context will return an ai_context similar to the following, where the lyrics are the 6 lines following the current playback time:

我们正在一起听歌，你现在跟我一起听xxx，曲风是xxx，歌手是xxx，当前的6句歌词是xxx

Note: The MCP Server itself cannot 100% force Claude to call a tool before every response. The recommended instructions above will strongly constrain Claude to actively call get_listening_context. If you need a hard guarantee, you need to build a proxy layer or a custom client to automatically inject the listening context before sending it to the model.

FAQ

Claude cannot see the tools

You need to restart Claude Desktop after modifying claude_desktop_config.json.

Also, confirm that src/server.js in the configuration is the correct absolute path.

PowerShell cannot find neteasecli

First, confirm installation:

npm install -g neteasecli

Then confirm that the npm global command directory is in your PATH. On Windows, it usually needs to include:

%APPDATA%\npm

If the command is temporarily unavailable, you can also run the globally installed CLI directly with Node:

node "$env:APPDATA\npm\node_modules\neteasecli\dist\index.js" auth login
node "$env:APPDATA\npm\node_modules\neteasecli\dist\index.js" --pretty auth check

How to log in to NetEase Cloud

neteasecli does not use SMS verification code login; it imports NetEase Cloud Music cookies from the browser:

1. Open https://music.163.com/ in Chrome or Edge and log in to your NetEase Cloud account.

2. Return to PowerShell and run:

neteasecli auth login

3. Check login status:

neteasecli --pretty auth check

You can also ask Claude to call it:

netease-music-mcp.setup_netease_login

It will check which step is missing and return the command you should run next.

neteasecli cannot find login cookies

If neteasecli auth login consistently fails to find login cookies in the browser, you can manually write the neteasecli session file. This is usually more direct than dealing with browser lock files.

The session file path for the default profile is:

C:\Users\<你的用户名>\.config\neteasecli\profiles\default\session.json

The file content only needs MUSIC_U at a minimum:

{"MUSIC_U":"这里填你从浏览器里拿到的值"}

How to get MUSIC_U:

1. Open https://music.163.com/ in Edge, Chrome, or another browser and log in.

2. Press F12 to open Developer Tools.

3. Go to Application.

4. Find Cookies -> https://music.163.com on the left.

5. Find the cookie named MUSIC_U and copy its Value.

Then execute in PowerShell:

New-Item -ItemType Directory -Force "$HOME\.config\neteasecli\profiles\default"
Set-Content -Encoding UTF8 "$HOME\.config\neteasecli\profiles\default\session.json" '{"MUSIC_U":"把这里替换成你的MUSIC_U"}'
neteasecli --pretty auth check

Smoke test reports mpv not found

First, confirm that it can be run directly in PowerShell:

mpv --version

If not, please install mpv first, or add the directory containing mpv.exe to your system PATH. If you are only developing locally, you can also place the portable mpv.exe in the project root; the .gitignore in the project already ignores local mpv binaries and DLLs to avoid accidental uploads to GitHub.

Music keeps playing after closing the web page

The web page is just the player interface; the actual audio is played by the background mpv.

To stop playback only:

netease-music-mcp.stop

To end the entire listening session and close the web player:

netease-music-mcp.shutdown

Manually stop background mpv

If you want to manually stop the background playback process, you can run this in Windows PowerShell:

Get-Process mpv,mpv.com -ErrorAction SilentlyContinue | Stop-Process -Force

Development

Enter the project directory:

cd netease-music-mcp

Run checks:

npm run check
npm run smoke

Start Web UI:

node .\src\server.js --web-player --port 8765

Start MCP Server:

npm start