CloudMusic Desktop MCP

A small, local-only MCP server that lets an AI control the official NetEase Cloud Music desktop client on Windows.

It searches through the desktop client's own API (with an anonymous HTTPS fallback), opens one-off selections through the official orpheus:// protocol, and controls queues, playback modes, desktop lyrics, and app volume through a localhost-only Chromium control channel. It does not replace the official player or create a second playback process.

This is an independent community project. It is not affiliated with, endorsed by, or supported by NetEase Cloud Music.

Prerequisites

• Windows 10 or Windows 11.

• The official NetEase Cloud Music desktop client installed.

• A personal account signed in to the desktop client is recommended. The account determines which subscribed or paid tracks the client can play.

• Python 3.11 or newer.

• A local MCP host that can launch a stdio server, such as Codex or Claude Desktop.

The MCP never reads the signed-in account, browser cookies, credentials, listening history, playlists, or local music library.

Install

git clone https://github.com/Seraph310/cloudmusic-desktop-mcp.git
cd cloudmusic-desktop-mcp
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .

If the executable is installed outside a standard NetEase directory, set CLOUDMUSIC_EXE to its full path in the MCP configuration.

Codex configuration

Add the following to %USERPROFILE%\.codex\config.toml, replacing both paths:

[mcp_servers.cloudmusic]
command = 'C:\path\to\cloudmusic-desktop-mcp\.venv\Scripts\python.exe'
args = ['C:\path\to\cloudmusic-desktop-mcp\server.py']
startup_timeout_sec = 30

[mcp_servers.cloudmusic.env]
CLOUDMUSIC_EXE = 'C:\path\to\CloudMusic\cloudmusic.exe'

Restart the MCP host after changing its configuration.

Tools

When an artist is supplied, search_and_play refuses to play unless it finds one exact normalized title/artist match. This avoids silently choosing a cover version. Optional app shortcuts must first be configured to the matching global shortcuts inside NetEase Cloud Music.

The advanced stateful tools require Cloud Music to be launched with the local control channel. If get_netease_status reports queue_control_ready: false, close Cloud Music once and call launch_netease_music. The MCP starts it with the channel bound to 127.0.0.1 on port 9223. Set CLOUDMUSIC_CDP_PORT in the MCP environment to choose another local port.

Playback modes are order, list_loop, single_loop, and shuffle. set_netease_volume changes only Cloud Music's own volume, not Windows master volume. set_desktop_lyrics reads the current state before acting, so repeated requests do not accidentally toggle it the wrong way.

Desktop-lyrics themes are netease_red, sunset, cute_pink, sky_blue, fresh_green, vivid_purple, warm_yellow, and soft_gray.

Tested environment

• Windows 11 64-bit, build 26200.

• NetEase Cloud Music desktop client 3.1.24.204791.

• Python 3.11.5.

Other recent Windows client versions may work but have not yet been verified.

Safety choices

• HTTPS-only search.

• No Selenium, ChromeDriver, cookies, or account credentials.

• Advanced control is bound to 127.0.0.1 only and is never exposed remotely.

• Only fixed, allowlisted client actions plus validated song IDs and settings are evaluated.

• No arbitrary commands, URLs, keyboard input, or shell execution.

• Does not kill or restart an existing Cloud Music process.

• Opens only allowlisted orpheus:// commands built from numeric result IDs.

The queue integration uses internal actions in the tested official client version. A future NetEase update may rename them; use queue_control_ready and the returned state to diagnose compatibility.

Optional hardware companion

Pair this server with Halo PixelBar MCP so an MCP host can coordinate music with the speaker's ambient light, pixel screen, and independent hardware volume.

Related project

luuu-h/netease-music-mcp inspired this project and offers a different, feature-rich approach using neteasecli, mpv, synchronized lyrics, and a local web player. Choose that project when you want an independent player UI; choose this one when you want to keep using the official Windows desktop client without importing cookies into the MCP.

Test

.\.venv\Scripts\python.exe -m unittest discover -s tests -v

Credits

Built together by Celia and OpenAI Codex.

Celia led the product direction and live client validation. Codex assisted with reverse engineering, implementation, and testing.

License

MIT