ncm-mcp-server

网易云音乐 MCP Server。接到 Claude 官端后，Claude 可以直接搜歌、加歌、切歌、接一起听邀请、发私信。

全程只需要手机 SSH，不需要电脑抳 F12 cookie。

架构

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

写操作不走容器，因为公开镜像的 eapi 加密参数已经过期，一起听和私信全部 400。

文件

文件	作用
ncm_crypto.py	eapi / weapi 两套加密
ncm_client.py	请求层、cookie 和房间号读写
ncm_mcp_server.py	MCP 主服务，16 个工具
login.py	登录拿完整 cookie（qr / sms / password）
heartbeat.py	一起听心跳保活，给 cron 用
ncm-mcp.service	systemd 单元
nginx.conf.example	反代配置

部署

1. 拉代码、装依赖

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

旧版 pip 不认 --break-system-packages，直接用上面这行就行。如果报 externally-managed-environment，加上该参数重试。

2. 起读接口容器

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

出 JSON 就行。

3. 登录拿 cookie

建一个只有自己能读的目录，cookie 等同账号密码，别丢 /tmp：

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

然后选一种登录方式：

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

qr 模式在手机 SSH 里二维码可能挤得扫不出来，它会同时存一份 /tmp/ncm_qr.png。最稳的是 sms。

看到 [ok] logged in as … (uid=…) 就成了，把这个 uid 记下来，它是 AI 号的 uid。

4. 挂成服务

先改 ncm-mcp.service 里的 User 和路径对上你的实际用户，再：

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

看日志：

sudo journalctl -u ncm-mcp -f

启动时会打印容器可达性、cookie 长度和监听地址，三行都正常再往下走。

5. nginx 反代

把 nginx.conf.example 的内容贴进你域名的 HTTPS server 块：

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

返回 400/406 而不是 502，就说明反代通了（MCP 不吃裸 GET，报错是正常的）。502 代表后端没起来。

6. 心跳 cron

crontab -e

加一行（路径改成你自己的）：

* * * * * 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

没有活跃房间时它直接退出，不会乱发请求，可以一直挂着。

7. 接到 Claude

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

• URL：https://你的域名/ncm/mcp
• 名称：网易云音乐

连上后应该能看到 16 个工具。

使用

一起听

1. 你在网易云 APP 里给 AI 号发一起听邀请
2. 告诉 Claude：“我发了一起听邀请”
3. Claude 调 get_private_list → get_private_messages 解析出 roomId 和 inviterId
4. Claude 调 accept_listen_together 加入，房间号自动存下，cron 接手保活

点歌

1. Claude 调 search_music 拿 songId
2. add_song 加进列表
3. 你清一次 APP 后台重进（列表同步只能这么弄）
4. 之后 play_command 切歌，实时生效

工具清单

写操作：accept_listen_together end_listen_together listen_together_heartbeat listen_together_status get_room_playlist play_command add_song send_private_message

读操作：search_music get_song_detail get_private_list get_private_messages get_user_playlist get_playlist_detail get_login_status get_user_detail

兜底：http_request

安全

MCP 服务本身没有鲉权。它只听 127.0.0.1，靠 nginx 暴露。任何知道 https://你的域名/ncm/mcp 的人都能操作你的网易云账号。两个建议：

• 路径别用 /ncm/，换成一串随机字符，比如 /ncm-a7f3k9d2/
• 或者在 nginx 里加 header 校验，Claude 的 connector 支持自定义 header

cookie 等同账号密码，别提交进仓库，.gitignore 已经挡了。

排查

现象	原因
写操作全 400	cookie 不完整，缺 __csrf；重新跑 login.py
读操作报错	容器挂了，sudo docker restart ncmapi
一起听房间自己断	心跳没跑，看 heartbeat.log
nginx 502	服务没起，systemctl status ncm-mcp
Claude 连不上	证书问题或 URL 漏了 /mcp
加歌了但 APP 看不到	正常，清后台重进

致谢

基于 Iris & Rei 的接入教程实现。