# godot-cli-Referenz — Godot · AI Game Developer Wiki

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.

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

`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

```bash
npm install -g godot-cli
godot-cli --help
godot-cli <command> --help
```

Es 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-`PackageReference`s 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`. |

```bash
godot-cli install-plugin ./MyGodotProject
godot-cli install-plugin --version 0.34.0 ./MyGodotProject
godot-cli install-plugin --source ./Godot-MCP/addons/godot_mcp ./MyGodotProject
```

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

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

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

```bash
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 `gamedev` CLI: [App CLI](https://ai-game.dev/de/docs/wiki/app/cli).
- Unity und Unreal haben `unity-mcp-cli` und `unreal-mcp-cli`: siehe die Wikis [Unity MCP](https://ai-game.dev/de/docs/wiki/unity) und [Unreal MCP](https://ai-game.dev/de/docs/wiki/unreal).

---

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

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