unity-mcp-cli-Referenz

unity-mcp-cli ist das Kommandozeilen-Tool für Unity MCP. Es installiert Unity und das Plugin, meldet dich bei ai-game.dev an, schreibt KI-Agent-Konfigurationen, öffnet und schließt den Editor und ruft MCP-Tools auf oder führt C# im Editor von einem Terminal oder einem CI-Skript aus. Diese Seite listet alle Befehle und Flags in Version 1.6.2.

Installation#

npm install -g unity-mcp-cli

Oder führe jeden Befehl ohne Installation aus: npx unity-mcp-cli <command>. Es benötigt Node.js ^20.19.0 oder >=22.12.0 und läuft unter Windows, macOS und Linux. Befehle, die Editoren verwalten, nutzen die Unity Hub CLI; fehlt Unity Hub, installiert die CLI es.

Globale Optionen, für jeden Befehl verfügbar:

In einem nicht-interaktiven Terminal (CI) deaktiviert die CLI Spinner und Farben automatisch. Die meisten Befehle, die einen Projektpfad erwarten, akzeptieren ihn als positionelles Argument oder als --path und verwenden standardmäßig den aktuellen Ordner.

Eine typische Sitzung#

unity-mcp-cli install-plugin ./MyGame
unity-mcp-cli login
unity-mcp-cli setup-mcp claude-code ./MyGame
unity-mcp-cli open ./MyGame
unity-mcp-cli wait-for-ready ./MyGame
unity-mcp-cli run-tool tests-run ./MyGame --input '{"testMode":"EditMode"}'
unity-mcp-cli close ./MyGame

Befehle für die Projekteinrichtung#

install-unity#

Installiert einen Unity Editor über Unity Hub. Ohne Argument wird die neueste stabile Version installiert.

create-project#

Erstellt ein neues Unity-Projekt mit dem Editor: unity-mcp-cli create-project ./MyGame --unity 6000.3.1f1.

install-plugin#

Fügt die OpenUPM-Scoped-Registry und com.ivanmurzak.unity.mcp zu Packages/manifest.json hinzu. Eine höher installierte Version wird nie herabgestuft. Der Ordner muss ein Unity-Projekt sein.

install-extension#

Installiert eine offizielle Erweiterung in Packages/manifest.json. Siehe Erweiterungen.

remove-plugin#

Entfernt com.ivanmurzak.unity.mcp aus Packages/manifest.json und behält die Scoped Registries bei. Nimmt [path] (erforderlich, oder --path).

configure#

Blendet Tools, Prompts und Ressourcen in UserSettings/AI-Game-Developer-Config.json ein oder aus. Ein ausgeblendetes Element wird bei namentlichem Aufruf trotzdem ausgeführt.

bootstrap-local#

Fixiert die Konfiguration eines Projekts auf den Custom-(lokalen) Modus mit einer bestimmten Server-URL und einem Token. Idempotent.

Anmelde- und KI-Agent-Befehle#

login#

Meldet sich über den OAuth-Gerätefluss im Browser bei ai-game.dev an und speichert die Anmeldedaten in ~/.ai-game-dev/credentials.json. Das Editor-Plugin und die Desktop-App verwenden dieselben Anmeldedaten. Wenn du bereits angemeldet bist, wird das Programm vorzeitig beendet.

setup-mcp#

Schreibt die MCP-Konfiguration eines AI-Agents – dieselbe Ausgabe wie Configure im Editor-Fenster. Standardmäßig ist die URL auf dieses Projekt festgelegt (https://ai-game.dev/mcp/p/<pin>), und bei Cloud-HTTP-Konfigurationen enthält sie den Schlüssel dieses Projekts, wenn du angemeldet bist. Siehe AI-Clients verbinden.

setup-skills#

Erzeugt die Skill-Dateien des Agents über den laufenden Editor. Unity muss geöffnet sein und das Plugin verbunden ist.

Editor-Befehle#

open#

Öffnet das Projekt im Unity-Editor und setzt die Umgebungsvariablen für die Plugin-Verbindung anhand der angegebenen Optionen. Der Editor startet abgekoppelt.

Das Wegklicken des Startfehler-Dialogs erfordert unter macOS die Bedienungshilfen-Berechtigung für das Terminal und unter Linux X11 xdotool (Wayland wird nicht unterstützt).

close#

Schließt den Editor des Projekts sauber: unity-mcp-cli close ./MyGame --timeout 60 --force. Das Schließen eines nicht laufenden Editors gilt als erfolgreich.

wait-for-ready#

Fragt ab, bis der Editor und der MCP-Server Tool-Aufrufe annehmen. Optionen: [path], --url, --token, --timeout <ms> (Standard 120000) und --interval <ms> (Standard 3000).

status#

Zeigt an, ob Unity läuft, ob der lokale MCP-Server antwortet und ob der konfigurierte Server (zum Beispiel die Cloud) erreichbar ist. Optionen: [path], --url, --token, --timeout <ms> (Standard 5000).

Tool-Befehle#

run-tool#

Ruft ein MCP-Tool über die HTTP-API des Servers auf. URL und Token stammen aus der Projektkonfiguration (Custom- oder Cloud-Modus), sofern du sie nicht überschreibst.

unity-mcp-cli run-tool rql-query ./MyGame --input '{"query":"objects | where name == \"Player\" | select path name active"}'
unity-mcp-cli run-tool unity-tool-list ./MyGame --raw

run-system-tool#

Gleiche Optionen wie run-tool, für System-Tools, die nicht für MCP-Clients freigegeben sind (zum Beispiel Skill-Generierung und Sitzungssteuerung).

exec#

Führt C# im Editor über script-execute aus und gibt das Ergebnis aus. Ist ein Editor geöffnet, wird dieser verwendet; andernfalls startet ein Headless-Editor, der für spätere Aufrufe warm bleibt und nach --idle Sekunden beendet wird.

unity-mcp-cli exec 'GameObject.FindObjectsOfType<Camera>().Length'
echo 'Application.unityVersion' | unity-mcp-cli exec

Ein Kompilierfehler beendet mit Code 1 und verweist auf die betroffenen Zeilen.

Wartung#

update#

Aktualisiert die CLI auf die neueste npm-Version. --check prüft nur und beendet mit Code 2, wenn ein Update verfügbar ist. Unter npx gibt es nichts zu aktualisieren.

Nutzung als Bibliothek#

Das Paket exportiert außerdem eine typisierte Node.js-API (installPlugin, removePlugin, configure, setupMcp, installExtension und mehr), die Ergebnisobjekte zurückgibt, statt etwas auszugeben. Siehe die README des Pakets auf npm.

Verwandte Seiten#

• Installation und Erste Schritte.
• Konfiguration für die Umgebungsvariablen, die open setzt.
• Die eigene CLI der Desktop-App, gamedev: App-CLI.