CLI-Referenz
Komplette Referenz zu unreal-mcp-cli: Plugin installieren, anmelden, AI-Agents konfigurieren, Editor starten, Tools und Python ausführen.
unreal-mcp-cli ist das Kommandozeilen-Tool für Unreal MCP. Es installiert und aktualisiert das Plugin, meldet dich bei ai-game.dev an, schreibt MCP-Konfigurationen für AI-Agents, startet den Unreal Editor mit den passenden Verbindungseinstellungen und ruft Tools aus Skripten und CI auf. Es läuft unter Windows, macOS und Linux. Diese Seite beschreibt Version 0.26.2.
Die CLI installieren
Erfordert Node.js ^20.19.0 oder >=22.12.0.
npm install -g unreal-mcp-cli
unreal-mcp-cli --versionOder führe einen einzelnen Befehl ohne Installation aus:
npx unreal-mcp-cli@latest statusFühre unreal-mcp-cli <command> --help aus, um die integrierte Hilfe zu einem beliebigen Befehl zu erhalten. Das globale Flag -v, --verbose gibt zusätzliche Diagnoseinformationen aus.
Hinweis: Befehle, die das Projekt als [path] erwarten, nehmen es als positionales Argument an. Befehle ohne [path] nehmen es über -p, --path <dir>. Beide verwenden standardmäßig den aktuellen Ordner. Ein positionaler Pfad bei einem --path-Befehl schlägt mit "too many arguments" fehl.
Befehlsübersicht
| Befehl | Zweck |
|---|---|
create-project <path> | Legt ein minimales Unreal Engine C++-Projekt an |
install-plugin [path] | Installiert das UnrealMCP-Plugin in <project>/Plugins |
update [path] | Aktualisiert das installierte Plugin |
remove-plugin [path] | Entfernt das Plugin |
install-extension <id> [path] | Installiert eine Unreal MCP-Erweiterung |
login | Meldet dich bei ai-game.dev an (Device-Code-Flow) |
configure | Schreibt UNREAL_MCP_*-Werte in <project>/.env |
setup-mcp [agent] | Schreibt eine MCP-Konfiguration für einen AI-Agent |
setup-skills | Schreibt einen Skill für Claude Code im Projekt |
open [path] | Startet den Unreal Editor mit Verbindungseinstellungen |
close [path] | Schließt den Editor, in dem das Projekt läuft |
exec [code] | Führt Python im Editor aus |
status | Zeigt den Status von Paket, Projekt, Plugin und Verbindung |
wait-for-ready | Wartet, bis der MCP-Server des Projekts antwortet |
run-tool <tool> | Ruft ein MCP-Tool über HTTP auf |
run-system-tool <tool> | Ruft ein System-Tool über HTTP auf |
bootstrap-local [path] | Baut die Bridge aus dem Quellcode |
install-engine [version] | Erkennt installierte Engines und verlinkt auf den Epic Games Launcher |
Befehle für die Projekteinrichtung
create-project
Legt ein minimales C++-Projekt an. Optionen: --name <name> (Projekt- und Modulname; Buchstaben, Ziffern und Unterstriche, keine Bindestriche), --engine <version> (die EngineAssociation, zum Beispiel 5.7), --force (erlaubt einen nicht leeren Ordner).
unreal-mcp-cli create-project ./MyGame --engine 5.7install-plugin
Installiert das Plugin. Ohne lokale Quelle lädt es die zum CLI-Version passende Plugin-Quelle aus dem GitHub-Release herunter und prüft vorher deren Signatur.
| Flag | Bedeutung |
|---|---|
--version <v> | Herunterzuladende Plugin-Version (Standard: die CLI-Version) |
--plugin-source <dir> | Ein lokales Plugin-Verzeichnis verwenden (offline, CI, Entwicklung) |
--junction | Verlinken statt kopieren (Windows, für die Plugin-Entwicklung) |
--with-server | Lädt zusätzlich den per Prüfsumme verifizierten gamedev-mcp-server herunter |
--server-version <v>, --server-source <path-or-url> | Server-Version oder eine lokale bzw. eigene Quelle für --with-server |
--enroll <code>, --enroll-stdin | Löst einen Agent-Enrollment-Code ein statt einer Anmeldung im Browser |
--base-url <url> | Basis-URL für die Authentifizierung bei --enroll |
-y, --yes | Bestätigt den Wechsel des Rechners auf ein anderes Konto |
update
Synchronisiert das installierte Plugin erneut. Bei einem Versionswechsel entfernt es die veralteten Intermediate/ und die C++-Binaries/, damit Unreal sauber neu baut; die mitgelieferte Bridge bleibt erhalten. Flags: --version <v>, --plugin-source <dir>, --force (dieselbe Version neu installieren), --no-clean (Build-Cache behalten).
remove-plugin
Entfernt Plugins/UnrealMCP aus dem Projekt. Keine Optionen.
install-extension
Installiert eine Erweiterung, aktiviert sie und ihr Engine-Plugin in der .uproject. Flags: --version <x.y.z>, --source <dir>, --build (jetzt kompilieren), --engine-root <dir> (Engine für --build), --force.
unreal-mcp-cli install-extension com.ivanmurzak.unreal-ai-pcg ./MyGame --buildbootstrap-local
Baut die Bridge aus dem Quellcode nach <project>/Intermediate/UnrealMCP/ für Source-Checkouts; benötigt das .NET 9 SDK. Flags: --repo-root <dir>, --plan (nur den Build-Plan ausgeben).
install-engine
Listet installierte Engines auf oder prüft auf eine bestimmte Version. Es lädt nie eine Engine herunter; fehlt eine Version, erhältst du einen Link zum Epic Games Launcher. Flags: --manifest <path> (explizite LauncherInstalled.dat), --install, --yes.
Anmelde- und AI-Agent-Befehle
login
Meldet dich mit dem OAuth-Device-Code-Flow an und speichert die Anmeldedaten in ~/.ai-game-dev/credentials.json, die sich alle AI Game Dev-Tools auf dem Rechner teilen.
| Flag | Bedeutung |
|---|---|
-p, --path <dir> | Speichert die Anmeldedaten in der .env des Projekts statt im maschinenweiten Speicher |
--tools-only | Erstellt Anmeldedaten nur für Tools für CI-Runner (die App kann sie nicht verwenden) |
-y, --yes | Bestätigt den Wechsel des Rechners auf ein anderes Konto |
--base-url <url> | Basis-URL für die Authentifizierung (Standard https://ai-game.dev) |
--timeout <ms> | Gesamtes Timeout für das Polling |
configure
Schreibt UNREAL_MCP_*-Werte in <project>/.env und nimmt .env in die .gitignore auf. Flags: -p, --path, --mode <Cloud|Custom>, --host <url>, --cloud-url <url>, --token <token>, --auth <option>, --keep-connected, --tools <list>, --start-server, --transport <stdio|http>, --log-level <level>, --no-gitignore.
Mit --agent <id> bittet es stattdessen den verwalteten gamedev-mcp-server, eine angeheftete Client-Konfiguration zu schreiben; zugehörige Flags sind --url, --server-version und --server-source.
setup-mcp
Schreibt einen MCP-Konfigurationseintrag für einen Agent. Die Liste der Agents findest du unter AI-Clients verbinden.
| Flag | Bedeutung |
|---|---|
-p, --path <dir> | Projektordner |
--transport <t> | http (Standard) oder stdio (lädt den lokalen Server herunter) |
--url <url> | Explizite Server-URL |
--token <token> | Explizites Bearer-Token; hat Vorrang vor dem Projektschlüssel |
--oauth | Cloud: Konfiguration nur mit URL, der Agent meldet sich selbst an |
--regenerate-key | Cloud: einen neuen Projektschlüssel anlegen und den alten widerrufen |
--no-pin | Einfache /mcp-URL statt der projektgebundenen /mcp/p/<pin> |
--dry-run | Gibt das Snippet aus, ohne es zu schreiben |
--list | Listet unterstützte Agents und Konfigurationspfade auf |
setup-skills
Schreibt .claude/skills/unreal-mcp/SKILL.md. Flags: -p, --path, --url, --token, --force (überschreiben).
Editor-Befehle
open
Startet den Unreal Editor und übergibt die Verbindungseinstellungen als UNREAL_MCP_*-Umgebungsvariablen. Die Engine stammt aus der EngineAssociation des Projekts; eine selbst gebaute Engine benötigt --engine-root.
| Flag | Bedeutung |
|---|---|
--connection-mode <mode> | Custom oder Cloud; allein --host impliziert Custom |
--host, --token, --auth, --tools, --transport | Setzt die passende UNREAL_MCP_*-Variable |
--keep-connected, --start-server | Setzt die passende Variable auf true |
--no-connect | Übergibt keine UNREAL_MCP_*-Variablen |
--headless | Startet einen fensterlosen, von der CLI gesteuerten Editor und wartet, bis er bereit ist |
--idle <seconds>, --url <url> | Beenden im Leerlauf und Server-URL für einen von der CLI gesteuerten Editor |
--engine-root <dir> | Engine-Ordner für Source-Builds |
--no-build | Überspringt den Build der nativen Module vor dem Start |
--no-auto-dismiss-startup-dialogs | Lässt die Startdialoge von Unreal unangetastet |
--startup-dismiss-timeout-ms, --startup-dismiss-poll-interval-ms | Stimmt das Ausblenden der Dialoge ab (Standard 12000 und 1000) |
--no-cache | Ermittelt den Engine-Pfad neu |
Unter Linux funktioniert das Ausblenden der Startdialoge nur mit X11.
close
Schließt den Editor, in dem das Projekt läuft. Mit --owned-only schließt es nur einen Editor, den die CLI gestartet hat (über exec oder open --headless), der speichert und beendet wird; ein von dir geöffneter Editor wird nie angefasst. --force beendet einen von der CLI gesteuerten Editor, der nicht rechtzeitig schließt; --token überschreibt das Bearer-Token.
exec
Führt Python im Editor über python-execute aus. Es verwendet einen laufenden Editor weiter oder startet einen headless Editor, der off-screen rendert (Screenshots funktionieren also weiterhin) und sich nach einer Zeit ohne Tool-Aufrufe beendet.
unreal-mcp-cli exec "unreal.SystemLibrary.get_engine_version()" -p ./MyGameFlags: -p, --path, -f, --file <file> (- für stdin), --include <path> (Helfer aus .ai-game-dev/snippets, wiederholbar), --window, --idle <seconds> (Standard 300, 0 = nie), --ready-timeout <ms>, --timeout <ms>, --raw (die JSON-Antwort ausgeben), --url, --token, --engine-root, --no-build. Ergebnisse werden auf stdout ausgegeben, print()- und Log-Zeilen auf stderr.
Tool- und Status-Befehle
status und wait-for-ready
status meldet den Status von CLI, Projekt, Plugin und Verbindung, mit einer Live-Erreichbarkeitsprüfung (--no-probe überspringt sie). wait-for-ready blockiert, bis der Server auf einen Ping antwortet (--timeout, Standard 120000 ms; --interval, Standard 2000 ms). Beide akzeptieren -p, --path, --url und --token.
run-tool und run-system-tool
Ruft ein Tool über den lokalen MCP-Server des Projekts auf:
unreal-mcp-cli run-tool rql-query -p ./MyGame --input '{"query":"actors | select Label"}'
unreal-mcp-cli run-system-tool ping -p ./MyGameFlags: -p, --path, --url, --token, --input <json>, --input-file <file> (- für stdin), --timeout <ms> (Standard 60000).
Dieselbe Logik gibt es als typisierte Bibliothek (import { openProject, runTool } from 'unreal-mcp-cli'), die von der AI Game Dev-App verwendet wird.