Content
# Netease Music MCP
A privacy-first, self-hosted Netease Music Model Context Protocol service. It provides
search, song details, lyrics, and personal playlist capabilities to any MCP-supported client,
while isolating local player control in device adapters.
> Not an official Netease Music project, and has no affiliation or endorsement from Netease.
## Supported Devices
- **Mac**: All general capabilities; comes with stable macOS Netease client control.
- **Windows**: Search, lyrics, details, playlists, and stdio/HTTP MCP available; local playback
control adapter not yet marked as stable.
- **Linux / VPS / NAS**: Suitable for hosting remote MCP; provides search, lyrics, details, and playlist
capabilities, does not manage desktop players.
- **Android / iPhone / New Devices**: Use a client that supports remote MCP to connect to your own
hosted HTTPS address to access general capabilities. Cloud services cannot bypass phone system
permissions to control another app; in-app song switching requires a separate local companion program.
See the full matrix in [Platform support](docs/PLATFORM_SUPPORT.md).
## Tools
### All Platforms
- `netease_status`: Reports the running platform and available device adapters.
- `netease_search`: Anonymously search for songs.
- `netease_song_detail`: Read song details.
- `netease_lyrics`: Read lyrics, translations, and romanization.
- `netease_playlist_auth_status`: Check playlist account capability configuration, does not return Cookie.
- `netease_playlist_list`: List playlists created by the current account.
- `netease_playlist_create`: Create a public or private playlist.
- `netease_playlist_add_songs`: Add songs to a specified playlist.
- `netease_playlist_remove_songs`: Remove songs from a specified playlist.
- `netease_listen_together_capabilities`: Report the current device's listen together capabilities.
### macOS Local Adapter
- `netease_launch`: Launch the official client.
- `netease_open_entity`: Open song, playlist, album, or artist pages.
- `netease_open_area`: Open private FM, download management, or song recognition.
- `netease_control`: Play/pause, previous, next.
- `netease_next_track`: Send a system-level next track command, does not control the screen.
- `netease_listen_together_invite`: Open the listen together invitation interface.
## Quick Start
Requires Node.js 20 or higher.
```bash
git clone https://github.com/tianyupaipai-cmd/netease-music-mcp.git
cd netease-music-mcp
npm ci
npm test
npm start
```
`npm start` uses stdio, suitable for local MCP clients. General configuration example:
```json
{
"mcpServers": {
"netease-music": {
"command": "node",
"args": ["/absolute/path/to/netease-music-mcp/src/server.js"]
}
}
}
```
This is not a proprietary format for any AI product; any desktop or self-built frontend that supports
stdio MCP can use the same service.
## Remote HTTP and Mobile Connection
First, create a 64-bit hexadecimal secret that only allows the current user to read:
```bash
mkdir -p ~/.netease-music-mcp
openssl rand -hex 32 > ~/.netease-music-mcp/http.secret
chmod 600 ~/.netease-music-mcp/http.secret
NETEASE_MCP_SECRET_FILE="$HOME/.netease-music-mcp/http.secret" npm run start:http
```
The service listens on `127.0.0.1:3303` by default. Please use your own HTTPS reverse proxy
or zero-trust tunnel in front of it, then add the final address
`https://your-domain.example/mcp/<64-bit secret>` to clients that support Streamable HTTP MCP.
Do not listen on the public network, do not submit or share the complete MCP URL. Mobile devices can
connect to this remote address, but the service will also go offline if the Mac sleeps or the hosting
server stops.
## Optional: Enable Personal Playlists
Account writing is disabled by default. The project does not read passwords, only loads `MUSIC_U` and
optional `__csrf` from a specified file:
```text
MUSIC_U=your value; __csrf=your value
```
Then configure:
```bash
export NETEASE_MCP_ACCOUNT_WRITE_ENABLED=1
export NETEASE_MCP_COOKIE_FILE=/absolute/path/to/netease.session
```
macOS users can run:
```bash
npm run import:session:macos
```
The script only saves whitelisted cookies, does not print secret values. POSIX systems require session
file permissions to be `600`; Windows please restrict file ACL to the current user. Creating, adding,
and removing song tools still require explicit `confirm: true` for this call.
## Security and Boundaries
- Does not save account passwords, cookies, `.env`, session files, and secret files are ignored by Git.
- Account writing tools are disabled by default and can only modify playlists owned by the current session account.
- Does not provide audio download, decryption, member bypass, or copyright restriction bypass.
- Does not call private chat interfaces, nor automatically send listen together messages.
- macOS playback control may require "Privacy & Security → Accessibility/Automation" authorization.
- `netease_next_track` uses system media commands, does not read the screen or click coordinates, but only
guarantees normal playback mode; whether the listen together room accepts track switching is decided by
the official client.
Read [SECURITY.md](SECURITY.md) before disclosing security issues.
## Development
```bash
npm ci
npm test
```
CI runs on macOS, Windows, and Linux with Node.js 20/22. Feel free to submit platform adapters, but
capabilities not tested on target devices must be marked as experimental.
## License
[MIT](LICENSE)
