mmd-mcp: MikuMikuDance und MME-Einstellungen per MCP unter Windows steuern

mmd-mcp ist ein stdio-MCP-Server für Windows zur Steuerung von MikuMikuDance (MMD) für Autorenarbeiten sowie von MME-Effekteinstellungen. Die Voraussetzungen sind eindeutig: Sie müssen unter Windows arbeiten, selbst MMD 9.32 x64 (japanische Version; der Server lehnt nicht unterstützte Versionen ab) gestartet haben und bereit sein, die Installation aus dem Quellcode selbst zu kompilieren (dazu sind Python x64 sowie die Komponente „Desktopentwicklung mit C++" von Visual Studio 2022/Build Tools erforderlich). Er startet MMD nicht automatisch und lauscht nicht im Netzwerk. Falls Ihre Umgebung diese Bedingungen nicht erfüllt oder Sie die Build-Toolchain nicht anfassen möchten, ist er nicht die erste Wahl.

Für wen er geeignet ist

• Personen, die unter Windows MMD-Animationen erstellen und Modelle, Kamera, Licht, Physik und Timeline programmatisch anpassen oder die EMM-Effektzuweisungen von MME bearbeiten und AVI-Videos exportieren möchten.
• Verifizierte Umgebung: japanische Version MMD 9.32 x64, japanisches Windows, Python 3.10 x64; andere MMD-Versionen werden abgelehnt, sodass Nutzer anderer Versionen dies als „nicht unterstützt" betrachten sollten.
• Nicht geeignet für: macOS-/Linux-Nutzer, Personen, die MMD noch nicht installiert haben oder eine nicht verifizierte Version verwenden, sowie Personen, die die Visual-Studio-C++-Komponenten nicht installieren möchten. Die offiziellen Nachweise erwähnen keine macOS-/Linux-Unterstützung; dies ist unbekannt.

Erster Versuch in 3 Minuten

Hinweis: Der Hauptweg ist nicht in 3 Minuten durchlaufen – das Kompilieren der DLL aus dem Quellcode dauert länger; „3 Minuten" bezieht sich auf die geringe Anzahl der Schritte.

Voraussetzungen:

1. Windows-Umgebung mit installiertem Python x64 (verifiziert: 3.10 x64).
2. Installiertes Visual Studio 2022 oder Build Tools mit der Komponente „Desktopentwicklung mit C++" (zum Kompilieren der nativen DLL).
3. Gestartete japanische Version MMD 9.32 x64 – der Server startet MMD nicht automatisch.

Installation (im Repository-Verzeichnis, offiziell angegebene PowerShell-Befehle):

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
cmd /c scripts\build_native.cmd

Der dritte Befehl kompiliert die native DLL – ein notwendiger Schritt; das Build-Ergebnis liegt lokal vor.

Registrierung beim MCP-Client (via stdio), offizielle Beispielkonfiguration:

"command": "C:/Tools/mmd-mcp/.venv/Scripts/python.exe",
"args": ["-m", "mmd_mcp.server"]

Der Pfad ist durch Ihre eigene venv-Position zu ersetzen.

Empfohlener erster Aufruf: mmd_list_windows – er listet nur Fenster auf, verändert die Szene nicht und ist der risikoärmste Erstaufruf. Erfolgssignal ist die Rückgabe der aktuellen MMD-Fensterliste samt hwnd. Wenn mehrere MMD-Instanzen laufen, muss bei jedem weiteren Aufruf das von mmd_list_windows zurückgegebene hwnd übergeben werden. Die offiziellen Nachweise sagen nicht, ob mmd_list_windows als readOnlyHint markiert ist; betrachten Sie kein Tool als absolut risikofrei.

Andere Installationswege: Offiziell ist nur der oben genannte Quellcode-Installationsweg angegeben; es gibt keine Hinweise auf pip-Pakete oder vorkompilierte Binärdateien.

Anwendungsbeispiele

Beispiel 1: Verbindung prüfen und mehrere Instanzen verwalten. Szenario: Sie haben den Client gerade konfiguriert und möchten prüfen, ob er MMD findet. Rufen Sie mmd_list_windows auf und beobachten Sie die zurückgegebene Fensterliste und die hwnd-Werte. Läuft nur eine MMD-Instanz, können Sie danach direkt andere Tools aufrufen; laufen mehrere, übergeben Sie laut offizieller Dokumentation bei jedem Aufruf das entsprechende hwnd, um das Ziel festzulegen. Bis zu diesem Punkt verifizierbar: Fensterenumeration und der hwnd-Übergabemechanismus; genaueres Ausgabeformat richtet sich nach der tatsächlichen Rückgabe.

Beispiel 2: Kamera-Keyframes im Batch schreiben und Video exportieren. Szenario: Sie haben eine Motion fertiggestellt und möchten die Kameraführung programmatisch setzen und als AVI ausgeben. Die offizielle v0.3.0 bietet 50 Tools; mmd_batch_camera_keys schreibt Kamera-Keyframes im Batch, mmd_export_video exportiert AVI. Beachten Sie: Beides sind Schreiboperationen auf dem aktuell geöffneten MMD-Projekt – das Schreiben von Keyframes und der Videoexport verändern bzw. erzeugen Projektdaten. Stellen Sie vor dem Aufruf sicher, dass das geöffnete Projekt verändert werden darf oder gesichert ist. Die offiziellen Nachweise erwähnen weder eine Undo-Möglichkeit noch Details zu Exportparametern; prüfen Sie vor dem Aufruf die konkreten Parameterdefinitionen im Client.

Nutzungsgrenzen

• Lese-/Schreibcharakter: Von den 50 Tools sind einige Abfragen zu Fenstern/Szenen, andere Schreiboperationen wie Modellauswahl, batchweises Schreiben von Skelett-/Kamera-Keyframes, Lesen und Schreiben von EMM-Effektzuweisungen (mmd_read_effect_assignments / mmd_write_effect_assignments) sowie der AVI-Export. Schreiboperationen wirken direkt auf Ihr geöffnetes MMD-Projekt.
• Umgebungsbindung: Die verifizierte Umgebung ist auf MMD 9.32 x64 beschränkt (japanische Version, offiziell per bestimmtem SHA-256 geprüft); nicht unterstützte Builds werden abgelehnt.
• Voraussetzungen und Nebenwirkungen: MMD muss vorher manuell gestartet werden; der Server startet MMD nicht automatisch und lauscht nicht im Netzwerk; bei mehreren Instanzen muss das hwnd zur Zielangabe übergeben werden, sonst ist das Ziel mehrdeutig.
• Lokale Änderungen: Die Installation erzeugt lokal eine venv und kompiliert die native DLL – notwendige lokale Änderungen.
• Unbestätigte Punkte: Die offiziellen Nachweise sagen nichts über Undo-Mechanismen, Details der Parameter der Schreiboperationen sowie Kompatibilität mit chinesischem/englischem Windows oder anderen Python-Versionen. Fehlende Informationen bedeuten nicht Abwesenheit von Risiken; sichern Sie Ihr Projekt, bevor Sie Schreiboperationen ausführen.