トラブルシューティング

Godot MCP の問題のほとんどは、次の4つのいずれかに起因します。間違った Godot ビルド、アドオンと一致しない .csproj、ビルドされていない C# アセンブリ、正しいサーバーを指していない AI クライアントです。表示されている症状に合うセクションを順に確認してください。解決しない場合は、ドックの Log Level を Debug に上げて問題を再現し、Output パネルを確認してください。

アドオンが読み込まれない#

初回起動時の「Unable to load addon script」#

Godot はエディタの起動と同時に、有効化されているアドオンをインスタンス化します。一度もビルドされたことのない C# プロジェクトを初めて開くときはアセンブリがまだ存在しないため、Godot は res://addons/godot_mcp/Editor/GodotMcpPlugin.cs を読み込めないと報告し、アドオンを無効化します。

解決策: まずビルドしてから、Project, Project Settings, Plugins でプラグインを再度有効にします。

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

godot-cli open はエディタを起動する前に必ずビルドするため、この問題を回避できます。

アドオンがコンパイルできない#

• 標準の Godot ビルドを使用しています。Godot MCP には Godot 4.3 以降の .NET (mono) ビルドが必要です。
• .csproj に NuGet パッケージが不足しているか、インストールしたアドオンとバージョンが異なります。godot-cli install-plugin を再実行するか、お使いのアドオンリリースのバージョンで Installation のブロックをコピーしてください。
• プロジェクトに .csproj がありません。Godot から C# ソリューションを作成するか、新規プロジェクトの場合は godot-cli create-project --dotnet を使用してください。
• .NET 8 SDK がインストールされていないか、PATH に含まれていません。

NuGet アセンブリの FileNotFoundException#

Godot はエディタ内でプロジェクトの NuGet パッケージを単独では解決しません。アドオンがビルドの .deps.json と NuGet キャッシュを読み取って解決します。それでもアセンブリが見つからない場合は、dotnet restore を実行して再度ビルドしてください。解決しない場合は .godot/mono/temp/obj と .godot/mono/temp/bin を削除してリビルドしてください。古いビルド出力が原因であることがほとんどです。

Play で起動したゲームが C# スクリプトを作成できない#

症状: TypeLoadException で EditorPlugin クラスが示された後、すべての C# スクリプトが「Cannot instantiate C# script because the associated class could not be found」で失敗します。.csproj に <EnableDynamicLoading>true</EnableDynamicLoading> が欠けているため、パッケージのアセンブリがゲームのアセンブリの隣にコピーされていません。<TargetFramework> の隣の <PropertyGroup> に追加してリビルドしてください。godot-cli install-plugin と create-project は自動で設定します。

Extensions リストが空#

ドックは拡張機能カタログをコンパイル済みのプロジェクトから読み取ります。.csproj に次の行が必要です。その後リビルドしてください。

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

LogicalName は正確に Godot-MCP.extensions.catalog.json である必要があります。ドックに .csproj が見つからないと表示される場合、アドオンが Godot の C# プロジェクト内にありません。Extensions を参照してください。

エディタが接続しない#

• クラウドモードで未サインイン。 ドックの Authorize をクリックするか、godot-cli login を実行してください。ドックにサインイン状態が表示されます。
• 環境変数による上書き。 「Overridden by environment (GODOT_MCP_*)」という黄色い注記が表示される場合、変数または .env ファイルがモードやホストを強制しており、ドックでの変更は反映されません。変数を削除するか変更してください。
• カスタムモードでサーバーなし。 ドックの Start Server をクリックするか、独自のサーバーを起動してください。オフラインの場合、サーバーのダウンロードは Output パネルに警告を出して失敗し、ローカルサーバーは起動しません。クラウドモードを使うか、すでにお持ちのサーバーを実行してください。
• リモートホストで oauth を使うカスタムモード。 アドオンはアカウントトークンを localhost のサーバーにのみ送信します。それ以外のホストでは GODOT_MCP_TOKEN を設定してください。設定しない場合、接続は「Refusing to send your ai-game.dev account token」で失敗します。

ターミナルから godot-cli status ./MyGodotProject と godot-cli wait-for-ready ./MyGodotProject で確認してください。

AI エージェントに Godot のツールが表示されない#

• 設定が書き込まれる前にエージェントを起動しました。再起動するか、その MCP サーバーを再読み込みしてください。
• Claude Code は起動したフォルダの .mcp.json を読み込みます。プロジェクトフォルダで起動するか、起動する場所に設定を書き込んでください。
• 複数のエディタが接続されていて、エージェントが素の /mcp URL を使用しています。setup-mcp がデフォルトで書き込む固定 URL を使用して、エージェントが正しいプロジェクトに接続できるようにしてください。
• 設定がエディタとは別のサーバー（クラウドかローカル）を指しています。モードを変更した後に godot-cli setup-mcp <agent> を再実行するか、ドックの Reconfigure をクリックしてください。
• ツールが非表示になっています。ドックの MCP 機能セクション、または godot-cli configure --list を確認してください。非表示のツールはエージェントに一覧表示されません。

C# のリビルド中にツール呼び出しが失敗する#

Godot は、ビルドされた DLL が変更されてから約 0.5 秒後にプロジェクトの C# アセンブリをリロードします（script-build、Build ボタン、または dotnet build）。アドオンはそのアセンブリの一部であるため、破棄・再ビルドされ、数秒以内に再接続します。リロードの前後では、新しい呼び出しはリトライ可能なエラー（"Godot is about to reload the project's C# assembly … Retry in a few seconds"）で拒否されます。待ってから再試行してください。script-build はリロード後に結果を返します。

.NET 10 でリロード後にエディタがクラッシュまたはハングする#

これは .NET ランタイムのバグです（dotnet/runtime#135441）。.NET 10 のサービス修正がリリースされるまで、エディタプロセスに次の環境変数を設定して Godot を再起動してください：

DOTNET_ThreadPool_ThreadsToKeepAlive=-1

Windows では setx DOTNET_ThreadPool_ThreadsToKeepAlive -1 で設定できます。godot-cli open や exec で起動したエディタには自動的に適用されます。.NET ランタイムに修正が含まれたら、この設定を削除してください。

呼び出しが古いビルドに送られる#

ツール呼び出しがコードの古いバージョンのように動作する場合、同じプロジェクトに対して複数のエディタが接続されている可能性があります（例：閉じ忘れたヘッドレスエディタ）。余分なものを閉じ（godot-cli close --owned-only は godot-cli が起動したエディタを閉じます）、1 つのエディタだけを接続したままにしてください。

ビルドが MissingMethodException で失敗する#

プロジェクトの Godot.NET.Sdk バージョンは、実行しているエディタと一致している必要があります。4.3 向けにビルドされたプロジェクトは、API が変更された 4.4 以降のエディタで MissingMethodException をスローする可能性があります。.csproj 内の Sdk="Godot.NET.Sdk/…" のバージョンをエディタのバージョンに更新して再ビルドしてください。

それでも解決しない場合#

FAQ とサイトの FAQ を確認するか、Godot-MCP issue tracker で Output パネルのログと Godot、.NET、アドオンのバージョンを添えて問題を報告してください。