godot-cli-Referenz
Alle godot-cli-Befehle und -Flags für Godot MCP – von install-plugin, login und setup-mcp bis open, exec, run-tool, configure und install-extension.
godot-cli ist das Kommandozeilen-Tool für Godot MCP, veröffentlicht auf npm. Es installiert das Addon, meldet dich an, schreibt Konfigurationen für KI-Agenten, baut und öffnet den Editor mit den richtigen Verbindungseinstellungen und ruft Tools aus Skripten auf. Diese Seite listet jeden Befehl in godot-cli 0.34.0 mit seinen Flags auf.
Installation und Grundlagen
npm install -g godot-cli
godot-cli --help
godot-cli <command> --helpEs benötigt Node.js ^20.19.0 oder >=22.12.0 und läuft unter Windows, macOS und Linux. Du kannst jeden Befehl auch ohne Installation ausführen: npx godot-cli <command>.
Die meisten Befehle nehmen den Projektordner als optionales positionales Argument [path] (oder --path <path>) und verwenden standardmäßig den aktuellen Ordner. Jeder Befehl akzeptiert -v / --verbose für Diagnoseausgaben.
Befehlsübersicht
| Befehl | Was er tut |
|---|---|
install-plugin [path] | Installiert das Addon, patcht die .csproj, aktiviert das Plugin. |
install-extension <id> [path] | Fügt ein Erweiterungspaket in der .csproj hinzu oder aktualisiert es. |
remove-plugin [path] | Deaktiviert das Addon in project.godot (Dateien bleiben erhalten). |
create-project [path] | Erstellt ein minimales Godot-4-Projekt. |
build [path] | Baut die C#-Assembly des Projekts. |
open [path] | Baut und öffnet dann den Godot-Editor mit Verbindungseinstellungen. |
close [path] | Beendet den für das Projekt laufenden Godot-Editor. |
exec [code] | Führt C# im Editor über script-execute aus. |
login [path] | Meldet sich mit dem Device-Flow bei ai-game.dev an. |
setup-mcp <agent> [path] | Schreibt die MCP-Konfiguration eines KI-Agenten. |
setup-skills <agent> [path] | Erzeugt Skill-Dateien für einen KI-Agenten. |
configure [path] | Blendet Tools, Prompts und Ressourcen ein oder aus. |
run-tool <tool> [path] | Ruft ein MCP-Tool über HTTP auf. |
run-system-tool <tool> [path] | Ruft ein System-Tool über HTTP auf. |
status [path] | Prüft den Editor und den MCP-Server. |
wait-for-ready [path] | Wartet, bis der Editor auf ping antwortet. |
update | Aktualisiert godot-cli selbst. |
install-plugin
Installiert das godot_mcp-Addon vollständig: lädt das Addon-Release von GitHub herunter (oder kopiert ein lokales), fügt die NuGet-PackageReferences und das <EmbeddedResource> des Erweiterungskatalogs zur .csproj hinzu, setzt EnableDynamicLoading und aktiviert das Plugin in project.godot. Kann gefahrlos erneut ausgeführt werden.
| Flag | Bedeutung |
|---|---|
--source <path> | Kopiert das Addon aus einem lokalen Ordner, statt es herunterzuladen (offline, Entwicklung, CI). |
--version <x.y.z> | Herunterzuladendes Addon-Release. Standardmäßig die Version der CLI. Wird bei --source ignoriert. |
--with-server | Lädt zusätzlich die passende gamedev-mcp-server-Binary herunter und prüft sie gegen die Checksummen des Releases. |
--server-source <path> | Installiert den Server aus einem lokalen Ordner oder einer .zip. Impliziert --with-server. |
--server-version <x.y.z> | Herunterzuladende Serverversion. Standardmäßig die im Addon festgelegte Serverversion. |
--enroll <code> | Löst einen Agent-Enrollment-Code ein (meldet das Plugin ohne Browser an). |
--enroll-stdin | Liest den Enrollment-Code aus stdin, damit er nicht in der Shell-Historie landet. |
--base-url <url> | Cloud-URL, gegen die der Enrollment-Code eingelöst wird. Standard https://ai-game.dev. |
godot-cli install-plugin ./MyGodotProject
godot-cli install-plugin --version 0.34.0 ./MyGodotProject
godot-cli install-plugin --source ./Godot-MCP/addons/godot_mcp ./MyGodotProjectinstall-extension
godot-cli install-extension <id> [path] löst die ID (Paket-ID oder Name) im Erweiterungskatalog auf und fügt deren <PackageReference> hinzu oder aktualisiert sie. --version <x.y.z> fordert eine exakte Version statt der neuesten stabilen an. Führe danach godot-cli build aus. Siehe Extensions.
remove-plugin
Deaktiviert das Addon im Abschnitt [editor_plugins] von project.godot. Es löscht weder addons/godot_mcp/ noch die Einträge in der .csproj.
create-project
Erstellt ein minimales Godot-4-Projekt (project.godot und icon.svg). Ein vorhandenes Godot-, Unity- oder Unreal-Projekt wird nicht überschrieben.
| Flag | Bedeutung |
|---|---|
--dotnet | Erstellt zusätzlich eine C#-.csproj mit Godot.NET.Sdk (für Godot MCP erforderlich). |
--name <name> | Projektname. Standardmäßig der Ordnername. |
build
Führt dotnet build für die .csproj des Projekts aus, damit das Addon beim nächsten Öffnen des Editors geladen wird. Projekte ohne .csproj werden übersprungen.
| Flag | Bedeutung |
|---|---|
--configuration <cfg> | MSBuild-Konfiguration. Standard Debug. |
--dotnet-path <path> | Verwendet diese dotnet-Executable statt der aus PATH. |
open
Baut die C#-Assembly, findet den Godot-Editor und öffnet das Projekt. Schlägt der Build fehl, wird der Editor nicht gestartet. Der Editor wird in dieser Reihenfolge gesucht: --editor-path, die Umgebungsvariable GODOT_BIN oder GODOT4_BIN, eine Godot-Binary in PATH (unter Windows wird der .NET-Build bevorzugt), dann gängige Installationsordner.
| Flag | Bedeutung |
|---|---|
--editor-path <path> | Zu verwendende Godot-Editor-Executable. |
--no-build | Überspringt den C#-Build. |
--build-configuration <cfg> | Konfiguration für den Build vor dem Öffnen. Standard Debug. |
--no-connect | Öffnen ohne jegliche GODOT_MCP_*-Verbindungsvariablen. |
--mode <Cloud or Custom> | Setzt GODOT_MCP_CONNECTION_MODE. |
--url <url> | Setzt GODOT_MCP_HOST. |
--cloud-url <url> | Setzt GODOT_MCP_CLOUD_URL. |
--token <token> | Setzt GODOT_MCP_TOKEN. |
--auth <None or Required> | Setzt GODOT_MCP_AUTH_OPTION. |
--log-level <level> | Setzt GODOT_MCP_LOG_LEVEL (Trace, Debug, Info, Warning, Error, None). |
--headless | Startet einen fensterlosen Editor auf dem lokalen Server des Projekts und wartet, bis er bereit ist. Ein bereits laufender wird wiederverwendet. |
--idle-timeout <seconds> | Mit --headless: beendet nach so vielen Sekunden ohne Tool-Aufrufe (0 = nie). |
--ready-timeout <ms> | Mit --headless: wie lange gewartet wird, bis der Editor bereit ist. |
close
Beendet den für das Projekt laufenden Godot-Editor geordnet.
| Flag | Bedeutung |
|---|---|
--timeout <seconds> | Wie lange auf ein ordentliches Beenden gewartet wird. Standard 30. |
--force | Beendet den Editor erzwungen, wenn er nicht rechtzeitig beendet wird. |
--owned-only | Schließt nur einen Editor, den godot-cli gestartet hat (exec, open --headless), niemals deinen eigenen. Geöffnete Szenen werden vorher gespeichert. |
--token <token> | Mit --owned-only: Bearer-Token. Standard GODOT_MCP_TOKEN. |
exec
Führt C# im Editor des Projekts mit dem Tool script-execute aus. Der Code besteht aus einfachen Anweisungen; der letzte Ausdruck ist das Ergebnis. Läuft bereits ein Editor des Projekts, wird dieser wiederverwendet (deiner muss im Modus Custom sein und sein lokaler Server gestartet sein). Andernfalls baut exec das Projekt und startet einen headless-Editor, der mit einem lokalen Server verbunden ist und nach --idle Sekunden ohne Aufrufe beendet wird (Standard 300).
godot-cli exec '1 + 2' --path ./MyGodotProject
godot-cli exec -f snippet.cs --using MyGame.Gameplay
godot-cli exec 'Helper.Twice(21)' --include helpers| Flag | Bedeutung |
|---|---|
--path <path> | Projektordner. |
-f, --file <file> | Liest den Code aus einer Datei (- für stdin). |
--using <namespace> | Zusätzlicher Namespace. Wiederholbar. |
--include <path> | Hilfsdatei .cs oder Ordner unter <project>/.ai-game-dev/snippets. Wiederholbar. |
--window | Startet den Editor mit Fenster statt headless. |
--idle <seconds> | Leerlaufzeit, bevor ein gestarteter Editor beendet wird (0 = nie). |
--ready-timeout <ms> | Wie lange auf einen gestarteten Editor gewartet wird. |
--timeout <ms> | Timeout für Tool-Aufrufe. Standard 310000. |
--no-build | Nicht bauen, bevor ein Editor gestartet wird. |
--editor-path <path> | Ausführbare Godot-Editor-Datei. |
--url <url> | URL des lokalen MCP-Servers. Standard: der lokale Port des Projekts. |
--token <token> | Bearer-Token. Standard GODOT_MCP_TOKEN. |
--raw | Gibt die unverarbeitete Tool-Antwort als JSON aus. |
Ein Kompilierfehler verweist auf die Zeile im Snippet und beendet mit Code 1.
login
Meldet sich mit dem OAuth-2.1-Device-Flow bei ai-game.dev an und speichert die Anmeldedaten in ~/.ai-game-dev/credentials.json, die der Editor übernimmt. Siehe AI-Clients verbinden.
| Flag | Bedeutung |
|---|---|
--project <path> | Speichert stattdessen Anmeldedaten pro Projekt unter <path>/.ai-game-dev/. |
--base-url <url> | Anmeldung bei einem anderen Server. Standard https://ai-game.dev. |
--force | Meldet sich erneut an, auch wenn bereits Anmeldedaten vorhanden sind. |
--tools-only | CI-Modus: erstellt Anmeldedaten nur für Tools, die die Desktop-App nicht übernimmt. |
--yes | Ersetzt die Anmeldedaten eines anderen Kontos ohne Nachfrage. |
setup-mcp
godot-cli setup-mcp <agent> [path] schreibt die MCP-Konfiguration des Agents, standardmäßig fest an dieses Projekt gebunden. Die Agent-IDs und Konfigurationsdateien sind unter AI-Clients verbinden aufgeführt.
| Flag | Bedeutung |
|---|---|
--list | Listet alle Agent-IDs auf. |
--url <url> | Überschreibt den Server-Host, zum Beispiel einen lokalen Server. |
--token <token> | Überschreibt das Token. Standard GODOT_MCP_TOKEN. |
--no-pin | Schreibt die einfache /mcp-URL statt der fest gebundenen. |
--oauth | Cloud: Konfiguration nur mit URL; der Agent meldet sich mit seinem eigenen OAuth an. |
--regenerate-key | Cloud: erstellt einen neuen Projektschlüssel und widerruft den alten. |
setup-skills
godot-cli setup-skills <agent> [path] schreibt SKILL.md-Dateien für die Tool-Familien des Addons in den Skills-Ordner des Agents (zum Beispiel .claude/skills). Es ist kein laufender Editor nötig. --list zeigt die Skills-Unterstützung jedes Agents.
configure
Listet oder ändert in .godot-mcp/features.json, welche Tools, Prompts und Ressourcen MCP-Clients sehen. Ausgeblendete Einträge werden weiterhin ausgeführt, wenn sie über ihren Namen aufgerufen werden.
| Flag | Bedeutung |
|---|---|
--list | Zeigt die aktuelle Konfiguration. |
--enable-tools <names> / --disable-tools <names> | Zeigt Tools an oder blendet sie aus (kommagetrennt). |
--enable-all-tools / --disable-all-tools | Zeigt alle Tools an oder blendet sie aus. |
--enable-prompts <names> / --disable-prompts <names> | Zeigt Prompts an oder blendet sie aus. |
--enable-all-prompts / --disable-all-prompts | Zeigt alle Prompts an oder blendet sie aus. |
--enable-resources <names> / --disable-resources <names> | Zeigt Ressourcen an oder blendet sie aus. |
--enable-all-resources / --disable-all-resources | Alle Ressourcen ein- oder ausblenden. |
--agent <id> | Einen Agenten über die verwaltete Server-Binary konfigurieren (erfordert install-plugin --with-server). |
--url <url> | Mit --agent: Server-URL überschreiben. |
run-tool und run-system-tool
Ein Tool direkt über die HTTP-API des Servers aufrufen: run-tool sendet an /api/tools/<tool>, run-system-tool an /api/system-tools/<tool> (Tools, die vor MCP-Clients verborgen sind, wie ping).
godot-cli run-tool rql-query ./MyGodotProject --input '{"query":"nodes | select name class"}'
godot-cli run-system-tool ping ./MyGodotProject| Flag | Bedeutung |
|---|---|
--url <url> | Basis-URL des Servers. |
--token <token> | Bearer-Token. Standard GODOT_MCP_TOKEN. |
--input <json> | Tool-Argumente als JSON-String. |
--input-file <file> | Die JSON-Argumente aus einer Datei lesen. |
--raw | Rohes JSON ausgeben. |
--timeout <ms> | Timeout für Anfragen. Standard 60000. |
Ohne --url wird der Server aus GODOT_MCP_HOST gewählt, dann aus GODOT_MCP_CLOUD_URL, dann die Cloud, wenn GODOT_MCP_CONNECTION_MODE=Cloud, dann der registrierte Server des Projekts und schließlich der lokale Port des Projekts.
status und wait-for-ready
status erkennt einen laufenden Editor für das Projekt und prüft den Server (--url, --token, --timeout <ms>, Standard 5000). wait-for-ready fragt ping ab, bis der Editor antwortet (--url, --token, --timeout <ms> Standard 120000, --interval <ms> Standard 3000). In Skripten nach open verwenden.
update
godot-cli update prüft npm auf ein neueres godot-cli und installiert es; --check meldet nur.
Verwandte Themen
- Die AI Game Dev App hat ihre eigene
gamedevCLI: App CLI. - Unity und Unreal haben
unity-mcp-cliundunreal-mcp-cli: siehe die Wikis Unity MCP und Unreal MCP.