ncm-mcp-server

NetEase Cloud Music MCP Server. Once connected to the Claude desktop app, Claude can directly search songs, add songs, switch songs, accept Listen Together invitations, and send private messages.

All you need is SSH from your phone — no need to dig cookies out of DevTools on a computer.

Architecture

Claude.ai
  ↓ MCP (HTTPS)
nginx  你的域名/ncm/mcp
  ↓
ncm_mcp_server.py  127.0.0.1:3940
  ├─ 读操作 → NeteaseCloudMusicApi 容器 :3939
  └─ 写操作 → 本地 eapi/weapi 加密 → 网易云官方接口

Write operations don't go through the container, because the eapi encryption parameters in the public image are already expired — Listen Together and private messages all return 400.

Files

Deployment

1. Pull the code, install dependencies

cd ~
git clone https://github.com/1049376904-crypto/ncm-mcp-server.git
cd ncm-mcp-server
sudo pip3 install -r requirements.txt

Older pip versions don't recognize --break-system-packages, so just use the line above directly. If you get an externally-managed-environment error, add that flag and retry.

2. Start the read-interface container

sudo docker run -d -p 3939:3000 --restart=always \
  --name ncmapi binaryify/netease_cloud_music_api:latest

curl -s "http://localhost:3939/search?keywords=test" | head -c 120

Just needs to output JSON.

3. Log in to get the cookie

Create a directory only you can read — the cookie is equivalent to your account password, don't leave it in /tmp:

mkdir -p ~/.ncm && chmod 700 ~/.ncm
export NCM_COOKIE_FILE=~/.ncm/music_cookie.txt
export NCM_ROOM_FILE=~/.ncm/listen_room_id.txt

Then pick a login method:

python3 login.py sms       # 推荐：手机号 + 短信验证码
python3 login.py qr        # 终端直接画二维码，网易云 APP 扫
python3 login.py password  # 手机号 + 密码（网易云经常拦）

In qr mode, the QR code may be too cramped to scan in a phone SSH session; it also saves a copy to /tmp/ncm_qr.png. The most reliable option is sms.

Once you see [ok] logged in as … (uid=…), you're done — write down that uid, it's the AI account's uid.

4. Register as a service

First edit User and the paths in ncm-mcp.service to match your actual user, then:

sudo cp ncm-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now ncm-mcp
sudo systemctl status ncm-mcp --no-pager

Check the logs:

sudo journalctl -u ncm-mcp -f

On startup it prints container reachability, cookie length, and the listen address — only move on once all three lines look normal.

5. nginx reverse proxy

Paste the contents of nginx.conf.example into your domain's HTTPS server block:

sudo nginx -t && sudo systemctl reload nginx
curl -i https://你的域名/ncm/mcp

If you get 400/406 instead of 502, the reverse proxy is working (MCP doesn't accept bare GET requests, so the error is expected). 502 means the backend isn't up.

6. Heartbeat cron

crontab -e

Add a line (change the path to yours):

* * * * * NCM_COOKIE_FILE=/home/ubuntu/.ncm/music_cookie.txt NCM_ROOM_FILE=/home/ubuntu/.ncm/listen_room_id.txt /usr/bin/python3 /home/ubuntu/ncm-mcp-server/heartbeat.py >> /home/ubuntu/.ncm/heartbeat.log 2>&1

If there's no active room it just exits without sending stray requests, so you can leave it running indefinitely.

7. Connect to Claude

Claude.ai → Settings → Connectors → Add custom connector:

• URL: https://your-domain/ncm/mcp

• Name: NetEase Cloud Music

Once connected you should see 16 tools.

Usage

Listen Together

1. In the NetEase Cloud Music app, send the AI account a Listen Together invitation

2. Tell Claude: "I sent a Listen Together invitation"

3. Claude calls get_private_list → get_private_messages to parse out the roomId and inviterId

4. Claude calls accept_listen_together to join; the room ID is saved automatically and cron takes over keep-alive

Requesting songs

1. Claude calls search_music to get the songId

2. add_song adds it to the list

3. You clear the app from the background once and reopen it (that's the only way to sync the list)

4. After that, play_command switches songs in real time

Tool list

Write operations: accept_listen_together end_listen_together listen_together_heartbeat listen_together_status get_room_playlist play_command add_song send_private_message

Read operations: search_music get_song_detail get_private_list get_private_messages get_user_playlist get_playlist_detail get_login_status get_user_detail

Fallback: http_request

Security

The MCP service itself has no authentication. It only listens on 127.0.0.1 and is exposed through nginx. Anyone who knows https://your-domain/ncm/mcp can operate your NetEase Cloud Music account. Two suggestions:

• Don't use /ncm/ as the path — swap it for a random string, e.g. /ncm-a7f3k9d2/

• Or add header validation in nginx; Claude's connector supports custom headers

The cookie is equivalent to your account password — don't commit it to the repo; .gitignore already blocks it.

Troubleshooting

Credits

Implemented based on the integration tutorial by Iris & Rei.