ncm-mcp-server

NetEase Cloud Music MCP-Server. Nach der Verbindung mit dem offiziellen Claude-Client kann Claude direkt Songs suchen, Songs hinzufügen, Songs wechseln, Einladungen zum gemeinsamen Hören annehmen und private Nachrichten senden.

Der gesamte Ablauf benötigt nur SSH vom Handy, kein F12-Cookie-Auslesen am Computer.

Architektur

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

Schreiboperationen laufen nicht über den Container, da die eapi-Verschlüsselungsparameter des öffentlichen Images abgelaufen sind – gemeinsames Hören und private Nachrichten liefern alle 400.

Dateien

Bereitstellung

1. Code ziehen, Abhängigkeiten installieren

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

Ältere pip-Versionen erkennen --break-system-packages nicht, einfach die obige Zeile verwenden. Falls ein externally-managed-environment-Fehler gemeldet wird, den Parameter hinzufügen und erneut versuchen.

2. Lese-API-Container starten

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-Ausgabe reicht.

3. Login für Cookie

Ein Verzeichnis anlegen, das nur man selbst lesen kann – das Cookie entspricht einem Kontopasswort, nicht nach /tmp legen:

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

Dann eine Login-Methode wählen:

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

Im qr-Modus kann der QR-Code im Handy-SSH zu klein zum Scannen sein; er speichert zusätzlich eine Kopie unter /tmp/ncm_qr.png. Am zuverlässigsten ist sms.

Sobald [ok] logged in as … (uid=…) erscheint, ist es geschafft. Diese uid notieren – es ist die uid des KI-Kontos.

4. Als Dienst einhängen

Zuerst User und Pfade in ncm-mcp.service an den tatsächlichen Benutzer anpassen, dann:

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

Logs ansehen:

sudo journalctl -u ncm-mcp -f

Beim Start werden Container-Erreichbarkeit, Cookie-Länge und Listen-Adresse ausgegeben – erst weitermachen, wenn alle drei Zeilen in Ordnung sind.

5. nginx-Reverse-Proxy

Den Inhalt von nginx.conf.example in den HTTPS-Server-Block deiner Domain einfügen:

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

Wenn 400/406 statt 502 zurückkommt, ist der Reverse-Proxy durchlässig (MCP akzeptiert kein nacktes GET, die Fehlermeldung ist normal). 502 bedeutet, dass das Backend nicht läuft.

6. Heartbeat-Cron

crontab -e

Eine Zeile hinzufügen (Pfade durch eigene ersetzen):

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

Wenn kein aktiver Raum vorhanden ist, beendet es sich direkt und sendet keine unnötigen Anfragen – es kann dauerhaft laufen.

7. Mit Claude verbinden

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

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

• Name: NetEase Cloud Music

Nach der Verbindung sollten 16 Tools sichtbar sein.

Verwendung

Gemeinsames Hören

1. Du sendest in der NetEase-Cloud-App eine Einladung zum gemeinsamen Hören an das KI-Konto

2. Sag Claude: „Ich habe eine Einladung zum gemeinsamen Hören gesendet“

3. Claude ruft get_private_list → get_private_messages auf, um roomId und inviterId zu parsen

4. Claude ruft accept_listen_together auf, um beizutreten; die Raumnummer wird automatisch gespeichert, cron übernimmt die Haltefunktion

Song anfordern

1. Claude ruft search_music auf, um die songId zu erhalten

2. add_song fügt sie zur Liste hinzu

3. Du schließt die App einmal im Hintergrund und öffnest sie neu (die Listensynchronisation funktioniert nur so)

4. Danach wechselt play_command den Song, wirkt in Echtzeit

Tool-Liste

Schreiboperationen: accept_listen_together end_listen_together listen_together_heartbeat listen_together_status get_room_playlist play_command add_song send_private_message

Leseoperationen: 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

Sicherheit

Der MCP-Dienst selbst hat keine Authentifizierung. Er lauscht nur auf 127.0.0.1 und wird über nginx exponiert. Jeder, der https://deine-domain/ncm/mcp kennt, kann dein NetEase-Cloud-Konto bedienen. Zwei Empfehlungen:

• Den Pfad nicht /ncm/ verwenden, sondern eine zufällige Zeichenfolge, z. B. /ncm-a7f3k9d2/

• Oder in nginx eine Header-Prüfung hinzufügen – der Claude-Connector unterstützt benutzerdefinierte Header

Das Cookie entspricht einem Kontopasswort, nicht ins Repository committen – .gitignore blockiert es bereits.

Fehlerbehebung

Danksagung

Implementiert auf Basis des Integrations-Tutorials von Iris & Rei.