# トラブルシューティング — Godot · AI Game Developer Wiki

アドオンが読み込まれない／コンパイルできない問題から、Extensions リストが空、ツールが見つからない、リロードエラー、.NET 10 のクラッシュまで、よくある Godot MCP の問題を解決します。

このページは英語から機械翻訳されています。[英語の原文を読む](https://ai-game.dev/docs/wiki/godot/troubleshooting)。

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** でプラグインを再度有効にします。

```bash
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](https://ai-game.dev/ja/docs/wiki/godot/installation#nuget-packages) のブロックをコピーしてください。
- プロジェクトに `.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` に次の行が必要です。その後リビルドしてください。

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

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

## エディタが接続しない

- **クラウドモードで未サインイン。** ドックの **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 を再起動してください：

```text
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](https://ai-game.dev/ja/docs/wiki/godot/faq) とサイトの [FAQ](https://ai-game.dev/docs/faq) を確認するか、[Godot-MCP issue tracker](https://github.com/IvanMurzak/Godot-MCP/issues) で Output パネルのログと Godot、.NET、アドオンのバージョンを添えて問題を報告してください。

---

Source (HTML): https://ai-game.dev/ja/docs/wiki/godot/troubleshooting

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