netease-music-mcp

Ein MCP-Server zur Steuerung der lokalen Musikwiedergabe. Er spielt Musik über neteasecli und das lokale mpv ab und stellt eine Web-UI für die Liedtextanzeige bereit.

Haftungsausschluss / Disclaimer

Dieses Projekt ist kein offizielles NetEase Cloud Music MCP und ist nicht mit NetEase Cloud Music verbunden, assoziiert oder von diesem unterstützt. Es dient ausschließlich dem persönlichen Lernen, der Forschung und lokalen Automatisierungsexperimenten. Bitte verwenden Sie es verantwortungsbewusst und halten Sie sich an die geltenden Nutzungsbedingungen, Urheberrechtsregeln und Richtlinien zur Kontonutzung von NetEase Cloud Music.

This project is not an official NetEase Cloud Music MCP and is not affiliated with, associated with, or endorsed by NetEase Cloud Music. It is intended for personal learning, research, and local automation experiments. Please use it responsibly and comply with the applicable NetEase Cloud Music terms of service, copyright rules, and account usage policies.

Sie können MCP-Clients wie Claude Desktop nutzen, um:

• Nach NetEase Cloud Music-Songs zu suchen und diese abzuspielen

• Musik anzuhalten, fortzusetzen, zu stoppen oder zu überspringen

• Den lokalen Web-Player zu öffnen: http://127.0.0.1:8765/

• Liedtexte, Playlists, Lieblingsmusik und die Vinyl-Wiedergabeseite anzuzeigen

• Vor der KI-Antwort den aktuellen Song, das Genre, den Interpreten und den Kontext des aktuellen Liedtextes auszulesen

• Beim Beenden des Musikhörens mpv per Knopfdruck zu stoppen und den Web-Player zu schließen

Systemanforderungen

Dieses Projekt ist derzeit primär für Windows konzipiert.

Erfordert das Upstream-Projekt: wangwalk/neteasecli. Der Code sucht standardmäßig nach der global installierten neteasecli unter %APPDATA%\npm\node_modules.

mpv ist eine Vorbedingung und muss vorab installiert werden. Stellen Sie sicher, dass mpv --version in der PowerShell ausgeführt werden kann.

neteasecli und mpv sind System-/globale Abhängigkeiten und werden nicht automatisch durch npm install installiert. Da die aktuelle Version von neteasecli Node.js 24 oder neuer erfordert, wird empfohlen, das gesamte Projekt direkt mit Node.js 24+ auszuführen. Falls Sie die portable Windows-Version von mpv.exe verwenden, können Sie diese auch temporär im Projektstammverzeichnis ablegen.

Installation

Projekt klonen:

git clone https://github.com/luuu-h/netease-music-mcp.git
cd netease-music-mcp

Projektabhängigkeiten installieren:

npm install

Musik-CLI global installieren:

npm install -g neteasecli

Loggen Sie sich zuerst im Browser bei der Webversion von NetEase Cloud Music ein. Die Anmeldemethode von neteasecli importiert Cookies aus dem Browser und speichert Ihr Passwort nicht im MCP.

https://music.163.com/

Importieren Sie dann den Anmeldestatus in der PowerShell:

neteasecli auth login

Falls Sie mehrere Chrome/Edge-Browser-Profile haben, können Sie das Profil angeben:

neteasecli auth login --profile "Profile 1"

Anmeldestatus bestätigen:

neteasecli --pretty auth check

Installieren Sie mpv. Wählen Sie eine der gängigen Methoden:

# Chocolatey
choco install mpv -y

# Scoop
scoop install mpv

Falls die PowerShell meldet, dass der Befehl neteasecli nicht gefunden wurde, stellen Sie sicher, dass das globale npm-Verzeichnis zum PATH hinzugefügt wurde. Unter Windows ist dies normalerweise %APPDATA%\npm.

Installation überprüfen

Syntaxprüfung:

npm run check

Smoke-Test:

npm run smoke

smoke prüft:

• Ob mpv im System-PATH oder im Projektstammverzeichnis gefunden werden kann

• Ob neteasecli global installiert ist

Sie können das Modell auch im MCP-Client aufrufen lassen:

netease-music-mcp.check_environment

Claude Desktop konfigurieren

Claude Desktop registriert lokale MCP-Server über die claude_desktop_config.json. Erst nach der Konfiguration kann Claude die Tools von netease-music-mcp sehen.

1. Absoluten Pfad des Projekts bestätigen

Führen Sie im Projektverzeichnis aus:

pwd

Angenommen, die Ausgabe ist:

C:\Users\you\projects\netease-music-mcp

Dann lautet der Pfad zur MCP-Server-Datei:

C:\Users\you\projects\netease-music-mcp\src\server.js

2. Claude Desktop Konfigurationsdatei öffnen

Öffnen Sie die Claude Desktop Konfigurationsdatei unter Windows:

notepad "$env:APPDATA\Claude\claude_desktop_config.json"

Falls der Pfad nicht gefunden wird, erstellen Sie das Verzeichnis zuerst:

New-Item -ItemType Directory -Force "$env:APPDATA\Claude"
notepad "$env:APPDATA\Claude\claude_desktop_config.json"

3. MCP-Konfiguration schreiben

Falls die Datei leer ist, fügen Sie den folgenden Inhalt ein. Achten Sie darauf, den Pfad durch Ihren eigenen Projektpfad zu ersetzen und doppelte Backslashes zu verwenden:

{
  "mcpServers": {
    "netease-music-mcp": {
      "command": "node",
      "args": [
        "C:\\path\\to\\netease-music-mcp\\src\\server.js"
      ]
    }
  }
}

Falls die Datei bereits andere MCP-Server enthält, fügen Sie nur den Eintrag "netease-music-mcp" zu den bestehenden "mcpServers" hinzu:

{
  "mcpServers": {
    "existing-server": {
      "command": "..."
    },
    "netease-music-mcp": {
      "command": "node",
      "args": [
        "C:\\path\\to\\netease-music-mcp\\src\\server.js"
      ]
    }
  }
}

4. Neustart und Überprüfung

Speichern Sie die Konfiguration, beenden Sie Claude Desktop vollständig und öffnen Sie es erneut.

Senden Sie dann in Claude:

请调用 netease-music-mcp.check_environment 检查我的本机音乐环境

Wenn die Rückgabe neteaseCliInstalled, mpvAvailable und den Anmeldestatus als normal anzeigt, können Sie mit der Musikauswahl beginnen.

Falls Sie noch nicht bei NetEase eingeloggt sind, können Sie senden:

请调用 netease-music-mcp.setup_netease_login 带我完成网易云登录

5. Häufige Konfigurationsfehler

• Windows-Pfade in JSON müssen doppelte Backslashes enthalten, z. B. C:\\path\\to\\file.js

• args muss auf src\\server.js zeigen, nicht auf den Projektordner

• Nach Konfigurationsänderungen muss Claude Desktop neu gestartet werden

• Falls Claude die Tools nicht sieht, stellen Sie sicher, dass node direkt in der PowerShell ausgeführt werden kann:

node -v

Web-Player separat starten

Wenn Sie die Web-UI direkt ohne Claude in der Vorschau sehen möchten:

node .\src\server.js --web-player --port 8765

Öffnen Sie dann im Browser:

http://127.0.0.1:8765/

Der Web-Player enthält:

• Gespeicherte Playlists

• Playlists erstellen

• Meine Lieblingsmusik

• Songsuche

• Playlist-Detailseite

• Player am unteren Rand

• Wiedergabeliste

• Vinyl-Liedtext-Wiedergabeseite

• Anzeige zweisprachiger Liedtexte bei CLI-Unterstützung

MCP-Toolliste

Empfohlene Claude-Anweisungen

Es wird empfohlen, den folgenden Abschnitt in die Projektanweisungen oder benutzerdefinierten Anweisungen von Claude aufzunehmen:

你可以使用 netease-music-mcp MCP 控制本机音乐。

当用户要配置、登录、安装、修复或检查 neteasecli 时，调用 netease-music-mcp.setup_netease_login，并按工具返回的 steps 带用户完成登录。用户执行完命令后，再调用一次 netease-music-mcp.setup_netease_login 或 netease-music-mcp.check_environment 验证。

当用户第一次要求播放音乐、点歌、听歌、打开播放器、查看歌词播放器，或当前对话还没有打开过播放器界面时，你必须先调用 netease-music-mcp.open_web_player，并把返回的 localhost URL 告诉用户。

当用户要求播放音乐时，调用 netease-music-mcp.play_song 或 netease-music-mcp.play_track。
当用户要求切歌时，调用 netease-music-mcp.next_song。
当用户要求暂停、继续、停止时，调用 netease-music-mcp.pause、netease-music-mcp.resume、netease-music-mcp.stop。

音乐播放期间，每次回复用户前，都必须先调用 netease-music-mcp.get_listening_context。
把返回的 ai_context 当作当前对话上下文使用。

点歌或切歌成功后，也要使用工具返回的 ai_context。
playback.style 字段已经优先来自网易云歌曲百科，可直接作为曲风/风格使用。

如果 netease-music-mcp.open_web_player 已经返回过 URL，不要重复打开，除非用户明确要求重新打开播放器。
如果用户问播放器在哪里，直接给出上次的 URL；如果不知道 URL，再调用 netease-music-mcp.open_web_player。

当用户说“结束听歌”、“不听了”、“关闭播放器”、“停止整个程序”，或任何表示要结束音乐/听歌会话的请求时，调用 netease-music-mcp.shutdown。这个工具只结束本次听歌和 Web 播放器，不会关闭 MCP 工具进程，因此之后仍然可以继续调用 netease-music-mcp。

Anwendungsbeispiel

In Claude Desktop können Sie sagen:

一起听歌吧，听歌过程中每次回复我之前请先看 listening_context
打开音乐播放器
播放 布拉格广场 蔡依林
切到 编号89757 林俊杰
暂停
继续
结束听歌

Wie der Musikhör-Kontext funktioniert

Nachdem ein Song gestartet wurde, speichert der Dienst die aktuellen Songinformationen in .listening-state.json:

• Song-ID

• Songtitel

• Interpret

• Album

• Cover-URL

• Songdauer

• Genre (vorzugsweise aus dem NetEase-Song-Lexikon)

• Liedtext mit Zeitstempel

• Übersetzter Liedtext, falls von der CLI bereitgestellt

get_listening_context gibt den ai_context zurück, der ähnlich wie folgt aussieht, wobei der Liedtext die 6 Zeilen nach der aktuellen Wiedergabezeit enthält:

我们正在一起听歌，你现在跟我一起听xxx，曲风是xxx，歌手是xxx，当前的6句歌词是xxx

Hinweis: Der MCP-Server selbst kann Claude nicht zu 100 % zwingen, vor jeder Antwort ein Tool aufzurufen. Die oben genannten empfohlenen Anweisungen zwingen Claude dazu, get_listening_context proaktiv aufzurufen. Wenn Sie eine strikte Garantie benötigen, müssen Sie eine Proxy-Ebene oder einen benutzerdefinierten Client erstellen, der den Musikhör-Kontext vor jeder Nachricht an das Modell automatisch injiziert.

Häufig gestellte Fragen

Claude sieht die Tools nicht

Nach dem Ändern von claude_desktop_config.json muss Claude Desktop neu gestartet werden.

Stellen Sie außerdem sicher, dass der absolute Pfad zu src/server.js in der Konfiguration korrekt ist.

PowerShell findet neteasecli nicht

Prüfen Sie zuerst die Installation:

npm install -g neteasecli

Stellen Sie dann sicher, dass das globale npm-Verzeichnis im PATH enthalten ist. Unter Windows muss dies normalerweise enthalten sein:

%APPDATA%\npm

Falls der Befehl vorübergehend nicht verfügbar ist, können Sie die global installierte CLI auch direkt mit Node ausführen:

node "$env:APPDATA\npm\node_modules\neteasecli\dist\index.js" auth login
node "$env:APPDATA\npm\node_modules\neteasecli\dist\index.js" --pretty auth check

Wie man sich bei NetEase einloggt

neteasecli verwendet keine SMS-Verifizierung, sondern importiert NetEase Cloud Music Cookies aus dem Browser:

1. Öffnen Sie https://music.163.com/ in Chrome oder Edge und loggen Sie sich in Ihr NetEase-Konto ein.

2. Gehen Sie zurück zur PowerShell und führen Sie aus:

neteasecli auth login

3. Anmeldestatus prüfen:

neteasecli --pretty auth check

Sie können Claude auch direkt aufrufen lassen:

netease-music-mcp.setup_netease_login

Es prüft, welcher Schritt fehlt, und gibt den Befehl für den nächsten Schritt zurück.

neteasecli findet keine Login-Cookies

Wenn neteasecli auth login die Login-Cookies im Browser nicht finden kann, können Sie die Session-Datei von neteasecli manuell schreiben. Dies ist oft direkter, als sich mit Browser-Lock-Dateien auseinanderzusetzen.

Der Pfad zur Session-Datei des Standardprofils ist:

C:\Users\<你的用户名>\.config\neteasecli\profiles\default\session.json

Der Dateiinhalt benötigt mindestens MUSIC_U:

{"MUSIC_U":"这里填你从浏览器里拿到的值"}

So erhalten Sie MUSIC_U:

1. Öffnen Sie https://music.163.com/ in Edge, Chrome oder einem anderen Browser und loggen Sie sich ein.

2. Drücken Sie F12, um die Entwicklertools zu öffnen.

3. Gehen Sie zu Application / Anwendung.

4. Suchen Sie links unter Cookies -> https://music.163.com.

5. Suchen Sie das Cookie mit dem Namen MUSIC_U und kopieren Sie dessen Value.

Führen Sie dann in der PowerShell aus:

New-Item -ItemType Directory -Force "$HOME\.config\neteasecli\profiles\default"
Set-Content -Encoding UTF8 "$HOME\.config\neteasecli\profiles\default\session.json" '{"MUSIC_U":"把这里替换成你的MUSIC_U"}'
neteasecli --pretty auth check

Smoke-Test meldet, dass mpv nicht gefunden wurde

Stellen Sie sicher, dass es direkt in der PowerShell ausgeführt werden kann:

mpv --version

Falls nicht, installieren Sie bitte mpv oder fügen Sie das Verzeichnis, in dem sich mpv.exe befindet, zum System-PATH hinzu. Wenn Sie nur lokal entwickeln, können Sie die portable mpv.exe auch im Projektstammverzeichnis ablegen; das .gitignore des Projekts ignoriert bereits lokale mpv-Binärdateien und DLLs, um ein versehentliches Hochladen auf GitHub zu vermeiden.

Musik spielt nach dem Schließen der Webseite weiter

Die Webseite ist nur die Player-Oberfläche; die eigentliche Audiowiedergabe erfolgt über das Hintergrundprogramm mpv.

Nur Wiedergabe stoppen:

netease-music-mcp.stop

Die gesamte Hörsitzung beenden und den Web-Player schließen:

netease-music-mcp.shutdown

Hintergrund-mpv manuell stoppen

Wenn Sie den Hintergrund-Wiedergabeprozess manuell stoppen möchten, können Sie dies in der Windows PowerShell tun:

Get-Process mpv,mpv.com -ErrorAction SilentlyContinue | Stop-Process -Force

Entwicklung

Wechseln Sie zuerst in das Projektverzeichnis:

cd netease-music-mcp

Prüfung ausführen:

npm run check
npm run smoke

Web-UI starten:

node .\src\server.js --web-player --port 8765

MCP-Server starten:

npm start