godot-mcp

Ein MCP-Server, der es einem KI-Agenten ermöglicht, an einem Godot-4.x-Projekt so zu arbeiten, wie es ein Entwickler tut: Szenen lesen und bearbeiten, Skripte schreiben, bauen, testen, ausführen, das Ergebnis ansehen und debuggen, was schiefgelaufen ist.

Zwei Dinge heben ihn vom Raten über Dateiformate oder blindem Shelling ab:

• Er fragt Godot selbst. Szenen- und Ressourcendateien werden strukturell geparst und neu serialisiert (nachweislich byte-identisch bei Round-Trips gegen einen realen Projektkorpus), aber alles, was vom eigenen Verhalten der Engine abhängt — C#-Introspection, Shader-Kompilierung, Eingabebindungen, Editor-Zustand — wird beantwortet, indem Godot tatsächlich headless ausgeführt oder ein laufender Editor abgefragt wird, nicht indem Godots Semantik aus dem Gedächtnis neu implementiert wird.

• Er scheitert laut. Jeder messbare Fehlermodus in diesem Projekt — ein fehlendes Display, eine nicht gebaute C#-Assembly, ein geschlossener Editor, ein Nicht-.NET-Binary — ist ein benannter, eindeutiger Fehler mit einer Abhilfe, kein stilles leeres Ergebnis. Siehe docs/capability-matrix.md für die Messungen, auf denen dies aufbaut; mehrere davon existieren speziell, weil sich das offensichtliche Signal (Exit-Code, ein Nicht-Null-Rückgabewert) als Lüge herausgestellt hat.

50 Tools, organisiert in vier Stufen danach, was sie zum Funktionieren benötigen. Siehe docs/tools.md für die vollständige Referenz und docs/troubleshooting.md für das, was zu tun ist, wenn ein Tool sich weigert.

Voraussetzungen

• Node.js >= 20

• Ein Godot-4.7+-Binary (die Fähigkeitsmatrix wurde gegen 4.7 gemessen; andere 4.x-Versionen sollten sich voraussichtlich ähnlich verhalten, sind aber unverifiziert)

• Für jedes C#-Tool (build_csharp, run_tests, csharp_script_info, validate_node_property und C#-Skriptpfade über validate_script): ein .NET/mono-Build von Godot — die gewöhnliche GDScript-only-Distribution kann .cs-Skripte nicht laden oder introspizieren, und jedes C#-Tool erkennt dies im Voraus und verweigert mit NOT_MONO_BINARY, anstatt mittendrin zu scheitern. Die --version-Ausgabe eines Mono-Builds enthält .mono. und er liefert ein Geschwisterverzeichnis GodotSharp/ mit.

• Speziell für die C#-Tools: ein dotnet-SDK auf PATH (build_csharp und run_tests rufen es direkt auf; csharp_script_info und validate_node_property benötigen, dass ein Debug-Build bereits existiert, der von build_csharp oder build_godot_artifacts stammt).

Related MCP server: godot-mcp-pilot

Installation und Build

git clone <this-repo> godot-mcp
cd godot-mcp
npm install
npm run build

Dies erzeugt dist/server.js, den Einstiegspunkt, den ein MCP-Client ausführt.

Konfigurieren eines MCP-Clients

Weisen Sie Ihren Client mit node auf dist/server.js und geben Sie ihm eine Möglichkeit, ein Godot-Binary zu finden. Das einfachste Setup setzt GODOT_PATH explizit:

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/path/to/godot-mcp/dist/server.js"],
      "env": {
        "GODOT_PATH": "/path/to/Godot_v4.7-stable_mono_linux.x86_64"
      }
    }
  }
}

Wie der Server ein Godot-Binary findet

In dieser Reihenfolge gewinnt das zuerst Gefundene:

1. Ein explizites binary-Argument, das einem Tool-Aufruf übergeben wird.

2. Die Umgebungsvariable GODOT_PATH.

3. Ein Binary, das unter dem eigenen vendor/-Verzeichnis des Projekts mitgeliefert wird (bis zu 3 Ebenen tief durchsucht, wobei eines bevorzugt wird, dessen Dateiname mono enthält) — für Projekte, die ihren eigenen Godot-Build mitbringen.

4. godot, godot4 oder godot-mono auf PATH.

Wie der Server ein Projekt findet

In dieser Reihenfolge:

1. Ein explizites project-Argument, das einem Tool-Aufruf übergeben wird.

2. Die Umgebungsvariable GODOT_PROJECT.

3. Aufwärtsgehen vom Arbeitsverzeichnis des Serverprozesses auf der Suche nach project.godot.

Wenn keines davon zu einem Verzeichnis mit project.godot auflöst, schlagen Tools, die ein Projekt benötigen, mit PROJECT_NOT_FOUND fehl.

GODOT_MCP_DOCS_CACHE

godot_class_doc und search_classes erstellen einen Klassenreferenz-Index, indem sie das Godot-Binary selbst befragen, was langsam genug ist, um einen Cache zu rechtfertigen. Der Index wird standardmäßig unter $TMPDIR/godot-mcp-docs-cache/<godot-version>/ geschrieben; setzen Sie GODOT_MCP_DOCS_CACHE, um ihn an einem persistenten Ort abzulegen. Der Cache ist nach Godot-Version verschlüsselt, sodass ein Upgrade des Binaries einen frischen Index erstellt, anstatt einen veralteten auszuliefern. Wenn Ihr MCP-Client den Server mit einem Arbeitsverzeichnis außerhalb des Zielprojekts ausführt, setzen Sie GODOT_PROJECT explizit:

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/path/to/godot-mcp/dist/server.js"],
      "env": {
        "GODOT_PATH": "/path/to/Godot_v4.7-stable_mono_linux.x86_64",
        "GODOT_PROJECT": "/path/to/your/godot-project"
      }
    }
  }
}

Rufen Sie in jeder neuen Sitzung zuerst godot_status auf — es meldet den aufgelösten Binary-Pfad, die Version, ob es ein Mono-Build ist, die Display-Verfügbarkeit, das Projektverzeichnis und ob die C#-Assembly gebaut ist, sodass ein Agent (oder Sie) sehen kann, was tatsächlich möglich ist, bevor etwas versucht wird.

Die vier Stufen

Jedes Tool wird von der niedrigsten Stufe bedient, die es beantworten kann. Wenn ein Tool mit TIER_UNAVAILABLE oder DISPLAY_REQUIRED fehlschlägt, ist dies der Grund:

Stufe D ist kein separater Transport — es ist eine Fähigkeitsbeschränkung zusätzlich zu Stufe B. Nur capture_screenshot ist Stufe D: Es gibt keinen Headless-Rendering-Pfad in Godot, daher erfordern Screenshots ein tatsächliches Display, virtuell oder physisch. run_project mit windowed: true hat dieselbe Anforderung.

Stufe-A-Tools (die meisten Szenen-, Knoten-, Skript- und Projektkonfigurationsbearbeitungen) funktionieren ganz ohne installiertes Godot — sie sind reine Dateioperationen, getestet gegen einen Korpus realer .tscn/.tres/project.godot-Dateien, die byte-identisch neu serialisiert werden. Stufe B benötigt ein Godot-Binary und/oder dotnet auf PATH oder wie oben aufgelöst. Stufe C benötigt das Editor-Addon (nächster Abschnitt) — bis es installiert ist und ein Editor mit aktiviertem Addon läuft, schlagen alle fünf Editor-Brücken-Tools mit TIER_UNAVAILABLE fehl; das ist erwartet, kein Fehler, und die Fehlermeldung sagt Ihnen, welche von zwei unterschiedlichen Situationen zutrifft (siehe docs/troubleshooting.md).

Siehe docs/tools.md für die Stufe jedes Tools.

Installieren des Editor-Addons (Stufe C)

Fünf Tools — editor_state, get_selected_node, live_scene_tree, open_scene_in_editor und execute_editor_script — kommunizieren über einen Loopback-TCP-Socket mit einem laufenden Godot-Editor, anstatt einen Prozess zu starten. Das erfordert ein kleines GDScript-Editor-Addon, das im Zielprojekt installiert und aktiviert ist. Es gibt kein Installations-Tool: In das addons/-Verzeichnis eines Benutzers zu schreiben und sein project.godot zu verändern, ist genau das, was die Pfad-Jail-Disziplin dieses Projekts zu vermeiden sucht, indem sie es nicht automatisch tut. Dies ist ein einmaliger manueller Schritt:

1. Kopieren Sie addon/godot_mcp/ aus diesem Repository in das addons/-Verzeichnis des Zielprojekts, sodass es unter <project>/addons/godot_mcp/plugin.cfg landet.

2. Aktivieren Sie das Plugin — entweder im Editor (Projekteinstellungen > Plugins > godot_mcp > Aktivieren) oder indem Sie es direkt zu project.godot hinzufügen:

   [editor_plugins]
   
   enabled=PackedStringArray("res://addons/godot_mcp/plugin.cfg")

3. Starten (oder neu starten) Sie den Godot-Editor für dieses Projekt — headless ist in Ordnung (--headless --editor --path <project>), kein Display erforderlich. Das Addon schreibt beim Start eine Handshake-Datei nach <project>/.godot/mcp_bridge.json; die fünf Tools lesen sie, um den Port der Brücke und das Sitzungs-Token zu finden.

Beachten Sie, dass der Editor-Auswahlzustand in einem Headless-Editor immer leer ist — das ist erwartet (get_selected_node meldet „nichts ausgewählt" als normales Ergebnis, nicht als Fehler).

Sicherheit und Umfang

• Pfad-Jail. Jeder Schreibpfad — Szene, Skript, Ressource, Screenshot-Ausgabe — wird aufgelöst und muss innerhalb des Projektverzeichnisses liegen. Ein Pfad, der es verlässt, direkt oder über einen Symlink, wird mit PATH_OUTSIDE_PROJECT abgelehnt, bevor irgendetwas angefasst wird.

• dry_run. Jedes mutierende Tool akzeptiert dry_run und gibt stattdessen einen vereinheitlichten Diff zurück. Verwenden Sie es, um eine Änderung zu prüfen, bevor Sie sich darauf festlegen.

• Kein Backup-Speicher. Versionskontrolle ist das Undo-System. Dies ist eine bewusste Vereinfachung — es gibt keinen Snapshot- oder Backup-Mechanismus im Server selbst. Wenn Ihr Projekt nicht unter Versionskontrolle steht, verwenden Sie dry_run vor jedem mutierenden Aufruf oder beginnen Sie, Versionskontrolle zu nutzen.

• execute_editor_script ist keine Sandbox. Es führt beliebiges GDScript in Ihrem tatsächlich laufenden Editorprozess aus, mit denselben Privilegien wie der Editor selbst — es kann Live-Editorzustand, die offene Szene und alles andere, was von GDScript aus erreichbar ist, lesen und verändern. Behandeln Sie es so, wie Sie es behandeln würden, einem Agenten eine Shell zu übergeben: geeignet für einen vertrauenswürdigen Agenten, der an Ihrem eigenen Projekt arbeitet, nicht für unvertrauenswürdige Eingaben.

Testen

npm test

Führt tsc --noEmit gegen sowohl tsconfig.json als auch tsconfig.test.json aus, dann die vollständige Vitest-Suite. Fast jeder Test ist auf Parser-Ebene: Er füttert vorgefertigte Godot/MSBuild-Ausgaben durch die Parser und prüft das strukturierte Ergebnis, sodass die Suite ohne Godot-Installation und ohne .NET-Toolchain läuft und schnell und portabel bleibt (CI, Container, ein Laptop mit keinerlei Installation).

GODOT_TEST_BINARY

Zwei Blöcke sind anders: tests/integration/tier-b.test.ts treibt ein echtes Godot-Binary an — baut temporäre Projekte auf der Festplatte und ruft validate_script, check_shaders, run_project und godot_class_doc dagegen auf — weil ein Parser ewig gegen vorgefertigten Text getestet werden kann, ohne jemals zu beweisen, dass der eigene Prozess-Spawning-, Argument-Aufbau- und Stream-Lese-Code des Tools tatsächlich gegen die echte Engine funktioniert. tests/integration/tier-c.test.ts tut dasselbe für die Editor-Brücken-Tools, mit einer materiell anderen Anforderung: Es muss einen echten Godot-Editor als langlebigen, abgekoppelten Prozess starten (Editoren beenden sich nicht von selbst) und ihn danach zuverlässig wieder einfangen, auch bei Testfehlern.

• Nicht gesetzt (Standard): beide Blöcke melden sich als SKIPPED. Nichts anderes in npm test ist betroffen.

• Gesetzt auf den Pfad eines Godot-4.7+-Binaries: beide Blöcke führen tatsächlich Ende-zu-Ende dagegen aus.

GODOT_TEST_BINARY=/path/to/Godot_v4.7-stable_linux.x86_64 npm test

Ein Mono/.NET-Build ist für diesen Block nicht erforderlich. Wenn Sie auch an den C#-orientierten Tools (build_csharp, run_tests) arbeiten, möchten Sie separat ein dotnet auf PATH haben; es gibt derzeit keine äquivalente Gate-Variable dafür, da keiner der Tests des GODOT_TEST_BINARY-Blocks sie benötigt.

Dokumentation

• docs/tools.md — jedes Tool, nach Bereich gruppiert, mit Stufe und wichtigsten Eingaben.

• docs/troubleshooting.md — gemessene Fehlermodi und ihre Behebungen.

• docs/capability-matrix.md — die empirischen Messungen, auf denen das Verhalten dieses Projekts aufbaut.