Fehlerbehebung

Die meisten Godot-MCP-Probleme haben eine von vier Ursachen: der falsche Godot-Build, eine .csproj, die nicht zum Addon passt, eine nicht gebaute C#-Assembly oder ein KI-Client, der nicht auf den richtigen Server zeigt. Arbeiten Sie den Abschnitt durch, der zu dem passt, was Sie sehen. Wenn Sie nicht weiterkommen, stellen Sie den Log Level des Docks auf Debug, reproduzieren Sie das Problem und lesen Sie das Output-Panel.

Das Addon lädt nicht#

"Unable to load addon script" beim ersten Öffnen#

Godot instanziiert aktivierte Addons, sobald der Editor startet. Beim allerersten Öffnen eines C#-Projekts, das noch nie gebaut wurde, gibt es noch keine Assembly, daher meldet Godot, dass res://addons/godot_mcp/Editor/GodotMcpPlugin.cs nicht geladen werden kann, und deaktiviert das Addon.

Lösung: zuerst bauen, dann das Plugin wieder unter Project, Project Settings, Plugins aktivieren.

godot-cli build ./MyGodotProject
godot-cli open ./MyGodotProject

godot-cli open baut immer, bevor es den Editor startet, daher vermeidet es dieses Problem.

Das Addon kompiliert nicht#

• Sie verwenden den Standard-Build von Godot. Godot MCP benötigt den .NET (mono)-Build von Godot 4.3 oder neuer.
• In der .csproj fehlen die NuGet-Pakete, oder sie enthält andere Versionen als das Addon, das Sie installiert haben. Führen Sie godot-cli install-plugin erneut aus, oder kopieren Sie den Block aus Installation mit den Versionen Ihres Addon-Releases.
• Das Projekt hat keine .csproj. Erstellen Sie die C#-Solution aus Godot heraus, oder verwenden Sie godot-cli create-project --dotnet für ein neues Projekt.
• Das .NET 8 SDK ist nicht installiert oder nicht im PATH.

FileNotFoundException für eine NuGet-Assembly#

Godot löst die NuGet-Pakete eines Projekts im Editor nicht von selbst auf; das übernimmt das Addon, indem es die .deps.json des Builds und Ihren NuGet-Cache liest. Wenn eine Assembly weiterhin nicht gefunden wird, führen Sie dotnet restore aus und bauen Sie erneut. Bleibt das Problem bestehen, löschen Sie .godot/mono/temp/obj und .godot/mono/temp/bin und bauen Sie neu: eine veraltete Build-Ausgabe ist die übliche Ursache.

Ein mit Play gestartetes Spiel kann keine C#-Skripte erstellen#

Symptom: Jedes C#-Skript schlägt mit "Cannot instantiate C# script because the associated class could not be found" fehl, nach einer TypeLoadException, die eine EditorPlugin-Klasse nennt. Ihrer .csproj fehlt <EnableDynamicLoading>true</EnableDynamicLoading>, daher werden die Paket-Assemblies nicht neben die Spiel-Assembly kopiert. Fügen Sie es in der <PropertyGroup> neben <TargetFramework> hinzu und bauen Sie neu. godot-cli install-plugin und create-project setzen es für Sie.

Die Extensions-Liste ist leer#

Das Dock liest den Extension-Katalog aus Ihrem kompilierten Projekt. Ihre .csproj benötigt diese Zeile, danach einen Neubau:

<EmbeddedResource Include="addons/godot_mcp/extensions.catalog.json" LogicalName="Godot-MCP.extensions.catalog.json" />

Der LogicalName muss exakt Godot-MCP.extensions.catalog.json lauten. Wenn das Dock meldet, dass keine .csproj gefunden wurde, befindet sich das Addon nicht in einem Godot-C#-Projekt. Siehe Extensions.

Der Editor verbindet nicht#

• Cloud-Modus, nicht angemeldet. Klicken Sie im Dock auf Authorize, oder führen Sie godot-cli login aus. Das Dock zeigt Ihren Anmeldestatus.
• Durch Umgebungsvariablen überschrieben. Ein gelber Hinweis "Overridden by environment (GODOT_MCP_*)" bedeutet, dass eine Variable oder eine .env-Datei den Modus oder Host erzwingt und Änderungen im Dock nichts bewirken. Entfernen oder ändern Sie die Variable.
• Custom-Modus, kein Server. Klicken Sie im Dock auf Start Server, oder starten Sie Ihren eigenen Server. Wenn Sie offline sind, schlägt der Server-Download mit einer Warnung im Output-Panel fehl und es startet kein lokaler Server; verwenden Sie den Cloud-Modus oder starten Sie einen Server, den Sie bereits haben.
• Custom-Modus mit oauth auf einem Remote-Host. Das Addon sendet Ihr Konto-Token nur an einen localhost-Server. Für andere Hosts setzen Sie GODOT_MCP_TOKEN, sonst schlägt die Verbindung mit "Refusing to send your ai-game.dev account token" fehl.

Prüfen Sie das aus einem Terminal mit godot-cli status ./MyGodotProject und godot-cli wait-for-ready ./MyGodotProject.

Der KI-Agent sieht keine Godot-Tools#

• Der Agent wurde gestartet, bevor seine Konfiguration geschrieben wurde. Starten Sie ihn neu, oder laden Sie seine MCP-Server neu.
• Claude Code liest .mcp.json aus dem Ordner, in dem es gestartet wird. Starten Sie es im Projektordner, oder schreiben Sie die Konfiguration dorthin, wo Sie es starten.
• Es sind mehrere Editoren verbunden, und der Agent verwendet die einfache /mcp-URL. Verwenden Sie die feste URL, die setup-mcp standardmäßig schreibt, damit der Agent das richtige Projekt erreicht.
• Die Konfiguration zeigt auf einen anderen Server als der Editor (Cloud vs. lokal). Führen Sie godot-cli setup-mcp <agent> erneut aus, nachdem Sie den Modus geändert haben, oder klicken Sie im Dock auf Reconfigure.
• Tools sind ausgeblendet. Prüfe den Abschnitt MCP features im Dock oder godot-cli configure --list. Ein ausgeblendetes Tool wird dem Agenten nicht aufgelistet.

Tool-Aufrufe schlagen während eines C#-Rebuilds fehl#

Godot lädt die C#-Assembly des Projekts etwa eine halbe Sekunde nach dem Ändern der erstellten DLL neu (script-build, die Schaltfläche Build oder ein dotnet build). Das Addon ist Teil dieser Assembly, daher wird es abgebaut, neu erstellt und verbindet sich innerhalb weniger Sekunden erneut. Rund um einen Reload werden neue Aufrufe mit einem wiederholbaren Fehler abgelehnt („Godot is about to reload the project's C# assembly … Retry in a few seconds“). Warte und versuche es erneut; script-build liefert sein Ergebnis nach dem Reload.

Der Editor stürzt nach einem Reload unter .NET 10 ab oder hängt#

Das ist ein Bug der .NET-Runtime (dotnet/runtime#135441). Bis der Servicing-Fix für .NET 10 erscheint, setze diese Umgebungsvariable für den Editor-Prozess und starte Godot neu:

DOTNET_ThreadPool_ThreadsToKeepAlive=-1

Unter Windows kannst du sie mit setx DOTNET_ThreadPool_ThreadsToKeepAlive -1 setzen. Editoren, die mit godot-cli open oder exec gestartet wurden, erhalten sie automatisch. Entferne sie wieder, sobald deine .NET-Runtime den Fix enthält.

Aufrufe gehen an einen alten Build#

Wenn sich Tool-Aufrufe wie eine ältere Version deines Codes verhalten, sind möglicherweise mehrere Editoren für dasselbe Projekt verbunden, zum Beispiel ein vergessener Headless-Editor. Schließe die überzähligen (godot-cli close --owned-only schließt Editoren, die godot-cli gestartet hat) und behalte einen verbundenen Editor.

Ein Build schlägt mit MissingMethodException fehl#

Die Version von Godot.NET.Sdk im Projekt sollte zum Editor passen, den du ausführst. Ein Projekt, das gegen 4.3 gebaut wurde, kann auf einem Editor 4.4 oder neuer, in dem sich APIs geändert haben, eine MissingMethodException auslösen. Aktualisiere die Version Sdk="Godot.NET.Sdk/…" in deiner .csproj auf deine Editor-Version und baue neu.

Immer noch festgefahren#

Prüfe die FAQ und die FAQ der Website oder melde das Problem im Godot-MCP-Issue-Tracker mit dem Log des Output-Panels und deinen Versionen von Godot, .NET und dem Addon.