# unity-mcp-cli-Referenz — Unity · AI Game Developer Wiki

Befehlsreferenz für unity-mcp-cli: Unity MCP installieren, anmelden, Agent-Konfigs schreiben, Unity headless öffnen, Tools und C# per CLI starten.

Diese Seite wurde maschinell aus dem Englischen übersetzt. [Englisches Original lesen](https://ai-game.dev/docs/wiki/unity/cli).

`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

```bash
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:

| Option | Beschreibung |
| --- | --- |
| `-v, --verbose` | Ausführliche Diagnoseausgabe |
| `-V, --version` | Gibt die CLI-Version aus |
| `--help` | Hilfe zum Befehl |

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

```bash
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.

| Argument / Option | Beschreibung |
| --- | --- |
| `[version]` | Editor-Version, zum Beispiel `6000.3.1f1` |
| `--path <path>` | Liest die benötigte Version aus einem bestehenden Projekt |

### create-project

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

| Argument / Option | Beschreibung |
| --- | --- |
| `[path]` | Wo das Projekt erstellt wird (erforderlich, oder `--path`) |
| `--unity <version>` | Editor-Version (Standard: höchste installierte) |

### 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.

| Option | Beschreibung |
| --- | --- |
| `[path]` | Unity-Projekt (Standard: aktueller Ordner) |
| `--plugin-version <version>` | Zu installierende Version (Standard: neueste auf OpenUPM) |
| `--with-server` | Lädt zusätzlich die `gamedev-mcp-server`-Binärdatei für diesen Rechner in den eigenen Ordner der CLI herunter |
| `--server-version <version>` | Serverversion für `--with-server` |
| `--server-source <path-or-url>` | Installiert den Server aus einem lokalen Zip oder einer URL (offline oder CI; überspringt die Prüfsummenverifikation) |
| `--enroll <code>` | Löst einen Team-Enrollment-Code für eine an dieses Projekt gebundene Plugin-Zugangsberechtigung ein |
| `--enroll-stdin` | Liest den Enrollment-Code aus stdin, sodass er nicht in der Shell-History landet |
| `--yes` | Bestätigt Rückfragen, etwa einen Kontowechsel während `--enroll` |

### install-extension

Installiert eine offizielle Erweiterung in `Packages/manifest.json`. Siehe [Erweiterungen](https://ai-game.dev/de/docs/wiki/unity/extensions).

| Argument / Option | Beschreibung |
| --- | --- |
| `[id]` | Katalogname (`Tilemap`) oder Paket-ID (`com.ivanmurzak.unity.mcp.tilemap`) |
| `[path]` | Unity-Projekt (Standard: aktueller Ordner) |
| `--extension-version <version>` | Zu installierende Version (Standard: neueste auf OpenUPM) |
| `--list` | Listet installierbare Erweiterungen auf und beendet (kein Projekt oder Netzwerk nötig) |

### 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.

| Option | Beschreibung |
| --- | --- |
| `[path]` | Unity-Projekt (erforderlich, oder `--path`) |
| `--list` | Gibt die aktuelle Konfiguration aus und beendet |
| `--enable-tools <names>`, `--disable-tools <names>` | Bestimmte Tools ein- oder ausblenden (kommagetrennt) |
| `--enable-all-tools`, `--disable-all-tools` | Alle Tools ein- oder ausblenden |
| `--enable-prompts <names>`, `--disable-prompts <names>` | Dasselbe für Prompts |
| `--enable-all-prompts`, `--disable-all-prompts` | Alle Prompts |
| `--enable-resources <names>`, `--disable-resources <names>` | Dasselbe für Ressourcen |
| `--enable-all-resources`, `--disable-all-resources` | Alle Ressourcen |
| `--agent <id>` | Schreibt stattdessen über den Configurator des verwalteten Servers eine KI-Agent-Konfiguration |
| `--url <url>` | Server-URL, die zusammen mit `--agent` übergeben wird |

### bootstrap-local

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

| Option | Beschreibung |
| --- | --- |
| `[path]` | Unity-Projekt (Standard: aktueller Ordner) |
| `--url <url>` | URL des lokalen MCP-Servers (erforderlich) |
| `--token <token>` | Lokales Bearer-Token (erforderlich) |
| `--dry-run` | Meldet, was sich ändern würde, ohne zu schreiben |

## 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.

| Option | Beschreibung |
| --- | --- |
| `--project <path>` | Speichert die Anmeldedaten in `<path>/.ai-game-dev/` statt im maschinenweiten Speicher |
| `--force` | Meldet dich erneut an, auch wenn bereits Anmeldedaten vorhanden sind |
| `--tools-only` | Autorisiert nur Engine-Tools für CI-Runner; es werden keine Agent-Anmeldedaten gespeichert |
| `--yes` | Bestätigt einen Kontowechsel ohne Rückfrage |

### 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](https://ai-game.dev/de/docs/wiki/unity/connecting-ai-clients).

| Option | Beschreibung |
| --- | --- |
| `[agent-id]` | Zu konfigurierender Agent, zum Beispiel `claude-code`, `cursor`, `codex` |
| `[path]` | Unity-Projekt (Standard: aktueller Ordner) |
| `--transport <transport>` | `http` (Standard) oder `stdio` |
| `--url <url>` | Überschreibt die Server-URL für `http` |
| `--token <token>` | Schreibt diesen Personal Access Token statt des Projektschlüssels |
| `--oauth` | Schreibt eine Konfiguration nur mit URL; der Agent meldet sich mit seinem eigenen OAuth an |
| `--regenerate-key` | Erzeugt einen neuen Projektschlüssel, schreibt die Konfigurationen neu und macht den alten Schlüssel ungültig |
| `--no-pin` | Verwendet den nicht festgelegten Endpunkt `https://ai-game.dev/mcp` |
| `--list` | Listet Agent-IDs und ihre Konfigurationspfade auf |

### setup-skills

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

| Option | Beschreibung |
| --- | --- |
| `[agent-id]` | Agent, für den Skills erzeugt werden |
| `[path]` | Unity-Projekt (Standard: aktueller Ordner) |
| `--url <url>`, `--token <token>` | Überschreibungen für Server-URL und Token |
| `--timeout <ms>` | Timeout für Anfragen (Standard 60000) |
| `--list` | Listet Agents und ob sie Skills unterstützen |

## 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.

| Option | Beschreibung |
| --- | --- |
| `[path]` | Unity-Projekt (Standard: aktueller Ordner) |
| `--unity <version>` | Editor-Version (Standard: die Version des Projekts, sonst die höchste installierte) |
| `--editor-path <path>` | Explizite Editor-Executable; überspringt die Suche über den Unity Hub |
| `--no-connect` | Öffnet ohne MCP-Verbindungsvariablen |
| `--url <url>` | Server-URL (setzt `UNITY_MCP_HOST`, den Alias von `UNITY_MCP_CLOUD_URL`) |
| `--keep-connected` | Erzwingt, dass die Verbindung aktiv ist |
| `--token <token>` | Token des lokalen Servers (setzt `UNITY_MCP_TOKEN`) |
| `--auth <option>` | Autorisierungsmodus (setzt `UNITY_MCP_AUTH_OPTION`); diese Version akzeptiert `none` oder `required` |
| `--tools <names>` | Kommagetrennte Tools, die angezeigt werden (setzt `UNITY_MCP_TOOLS`) |
| `--transport <method>` | `streamableHttp` oder `stdio` |
| `--start-server <value>` | `true` oder `false` für den automatischen Start des lokalen Servers |
| `--headless` | Startet ohne Fenster (`-batchmode`, Grafik bleibt aktiv) und wartet, bis der MCP-Server antwortet |
| `--idle-timeout <seconds>` | Beendet sich nach so vielen Sekunden ohne Tool-Aufruf und speichert vorher geänderte Szenen und Assets |
| `--ready-timeout <ms>` | Mit `--headless`: wie lange gewartet wird (Standard 300000) |
| `--no-auto-dismiss-launch-errors` | Klickt im Unity-Dialog "compile errors at launch" nicht auf **Ignore** |
| `--launch-dismiss-timeout-ms <ms>` | Gesamtzeit, in der auf diesen Dialog geachtet wird (Standard 30000) |
| `--launch-dismiss-poll-interval-ms <ms>` | Abfrageintervall für den Dialog (Standard 1500) |

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.

| Option | Beschreibung |
| --- | --- |
| `[path]` | Unity-Projekt (Standard: aktueller Ordner) |
| `--timeout <seconds>` | Wartet auf ein ordnungsgemäßes Beenden (Standard 30) |
| `--force` | Beendet den Editor gewaltsam, falls er bis dahin nicht geschlossen wurde |
| `--owned-only` | Schließt nur einen Editor, den die CLI gestartet hat (`exec`, `open --headless`) |

### 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.

```bash
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
```

| Option | Beschreibung |
| --- | --- |
| `<tool-name>` | Aufzurufendes Tool |
| `[path]` | Unity-Projekt, wird zur Konfigurations- und Porterkennung verwendet |
| `--url <url>`, `--token <token>` | Overrides, die die Konfiguration umgehen |
| `--input <json>`, `--input-file <file>` | Tool-Argumente (Standard `{}`) |
| `--raw` | Rohe JSON-Ausgabe |
| `--timeout <ms>` | Timeout der Anfrage (Standard 60000) |

### 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.

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

| Option | Beschreibung |
| --- | --- |
| `[code]` | C#-Anweisungen; der letzte Ausdruck ist das Ergebnis (oder `-f` bzw. stdin verwenden) |
| `--path <path>` | Unity-Projekt (Standard: aktueller Ordner) |
| `-f, --file <file>` | Code aus einer Datei lesen (`-` für stdin) |
| `--using <namespace>` | Zusätzlicher Namespace, wiederholbar |
| `--include <path>` | Hilfsdatei `.cs` oder Ordner unter `.ai-game-dev/snippets`, wiederholbar |
| `--window` | Editor mit Fenster statt headless starten |
| `--idle <seconds>` | Leerlaufzeit, bevor ein von `exec` gestarteter Editor beendet wird (Standard 300, 0 für nie) |
| `--ready-timeout <ms>` | Wartezeit auf den Editor (Standard 300000) |
| `--timeout <ms>` | Timeout für Tool-Aufrufe |
| `--raw` | Rohe Tool-Antwort als JSON |
| `--url <url>`, `--token <token>` | Overrides |

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](https://www.npmjs.com/package/unity-mcp-cli).

## Verwandte Seiten

- [Installation](https://ai-game.dev/de/docs/wiki/unity/installation) und [Erste Schritte](https://ai-game.dev/de/docs/wiki/unity/getting-started).
- [Konfiguration](https://ai-game.dev/de/docs/wiki/unity/configuration#overrides) für die Umgebungsvariablen, die `open` setzt.
- Die eigene CLI der Desktop-App, `gamedev`: [App-CLI](https://ai-game.dev/de/docs/wiki/app/cli).

---

Source (HTML): https://ai-game.dev/de/docs/wiki/unity/cli

Machine-translated (de) from the English page: https://ai-game.dev/docs/wiki/unity/cli