godot-mcp

AI エージェントが Godot 4.x プロジェクトで、開発者と同じように作業できるようにする MCP サーバーです。シーンの読み取り・編集、スクリプトの作成、ビルド、テスト、実行、結果の確認、失敗した箇所のデバッグまで行えます。

このサーバーが、ファイル形式を推測したり盲目的にシェルを呼び出したりする方法と一線を画すのは、次の 2 点です:

• Godot 自身に問い合わせます。 シーンとリソースファイルは構造的に解析・再シリアライズされます(実際のプロジェクトコーパスに対してラウンドトリップでバイト一致することが検証済み)。しかし、エンジン自身の挙動に依存するもの — C# のイントロスペクション、シェーダコンパイル、入力バインディング、エディタの状態 — は、Godot のセマンティクスを再実装するのではなく、実際に Godot をヘッドレスで起動するか、稼働中のエディタに問い合わせて回答します。

• 失敗をはっきり示します。 このプロジェクトで測定可能なすべての障害モード — ディスプレイなし、C# アセンブリ未ビルド、エディタが閉じている、非 .NET バイナリ — は、沈黙した空の結果ではなく、名前の付いた個別のエラーと対処法として報告されます。この設計の拠り所となった測定結果については docs/capability-matrix.md を参照してください。その中のいくつかは、一見もっともらしいシグナル（終了コードや非 null の戻り値）が実際には嘘をついていたことが判明したため、特別に設けられています。

50 個のツールは、動作に必要なものに応じて 4 つのティアに整理されています。完全なリファレンスは docs/tools.md、ツールが拒否した場合の対処法は docs/troubleshooting.md を参照してください。

要件

• Node.js >= 20

• Godot 4.7+ のバイナリ（capability-matrix は 4.7 で測定しました。他の 4.x バージョンも同様に動作する見込みですが、未検証です）

• C# ツール（build_csharp、run_tests、csharp_script_info、validate_node_property、および validate_script を経由する C# スクリプトパス）には、.NET/mono ビルドの Godot が必要です。通常の GDScript 専用ディストリビューションでは .cs スクリプトを読み込んだりoutrospectionしたりできません。すべての C# ツールはこれを事前に検出し、途中で失敗する代わりに NOT_MONO_BINARY で拒否します。mono ビルドの --version 出力には .mono. が含まれ、同等の GodotSharp/ ディレクトリが同梱されています。

• C# ツールに固有の要件として、PATH 上に dotnet SDK が必要です（build_csharp と run_tests はそれを直接呼び出しますが、csharp_script_info と validate_node_property は、build_csharp または build_godot_artifacts によって生成される Debug ビルドが既に存在していることを必要とします）。

Related MCP server: godot-mcp-pilot

インストールとビルド

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

これで、MCP クライアントが実行するエントリポイントである dist/server.js が生成されます。

MCP クライアントの設定

クライアントに dist/server.js を node で実行させ、Godot バイナリを見つける方法を与えます。最も簡単なのは、GODOT_PATH を明示的に設定することです。

{
  "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 バイナリを探す方法

次の順に、最初に一致したものが優先されます。

1. ツール呼び出しに渡された明示的な binary 引数。

2. GODOT_PATH 環境変数。

3. プロジェクト自身の vendor/ ディレクトリに同梱されたバイナリ（3 階層まで再帰的に検索し、ファイル名に mono を含むものを優先）— プロジェクトに独自の Godot ビルドを同梱する場合向け。

4. PATH 上の godot、godot4、または godot-mono。

サーバーがプロジェクトを探す方法

次の順に検索します。

1. ツール呼び出しに渡された明示的な project 引数。

2. GODOT_PROJECT 環境変数。

3. サーバープロセスの作業ディレクトリから上行し、project.godot を探す。

どれも project.godot を含むディレクトリに解決されない場合、プロジェクトを必要とするツールは PROJECT_NOT_FOUND で失敗します。

GODOT_MCP_DOCS_CACHE

godot_class_doc と search_classes は、Godot バイナリ自身に問い合わせてクラスリファレンスのインデックスを構築しますが、この処理はキャッシュする価値があるほど低速です。インデックスはデフォルトでは $TMPDIR/godot-mcp-docs-cache/<godot-version>/ の下に書き込まれます。GODOT_MCP_DOCS_CACHE を設定すると、永続的な場所に配置できます。キャッシュは Godot バージョンでキーされているため、バイナリをアップグレードすると古い情報を返し続けるのではなく、新しいインデックスが構築されます。MCP クライアントがターゲットプロジェクトの外部の作業ディレクトリでサーバーを実行する場合は、GODOT_PROJECT を明示的に設定してください。

{
  "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"
      }
    }
  }
}

新しいセッションでは、まず godot_status を呼び出してください。解決されたバイナリパス、バージョン、mono ビルドかどうか、ディスプレイの利用可否、プロジェクトルート、C# アセンブリがビルド済みかを報告するので、エージェント（またはあなた）は何かを試す前に実際に可能な範囲を確認できます。

4 つのティア

各ツールは、それに答えられる最も低いティアで提供されます。ツールが TIER_UNAVAILABLE や DISPLAY_REQUIRED で失敗する場合、その理由はこのとおりです。

| ティア | 仕組み | 要件 | | --- --- --- | --- --- --- | --- --- --- | | A — ファイル層 | .tscn・.tres・.cs・.gd・project.godot を直接読み書き | なし — Godot プロセスは一切不要 | | B — ヘッドレス CLI | godot --headless … と dotnet … のサブプロセス | Godot バイナリ、および/または dotnet SDK | | C — エディタブリッジ | GDScript エディタアドオンへの TCP ソケット | アドオンがインストールされ有効化されている、実行中の Godot エディタ（下記） | | D — ディスプレイ依存 | 図務フレームの描画をさらに必要とする Tier B のツール | Tier B に必要なすべてに加え、実際のディスプレイ（X11 または Wayland） |

Tier を uni 独立した転送手段ではなく、"Tier B" の上に重なる能力の制約です。Tier D に該当するのは capture_screenshot だけです。Godot にはヘッドレス描画の経路がないため、スクリーンショットには仮想・物理を問わず実際のディスプレイが必要です。windowed: true の run_project も同様の要件です。

Tier A のツール（シーン、ノード、スクリプト、プロジェクト構成の編集中の大部分）は、Godot がインストールされていなくても動作します。詰まるところ純粋なファイル操作であり、実在の .tscn・.tres・project.godot をコーパスとして再シリアライズがバイト単位で一致することを検証しています。Tier B は、Godot バイナリ、および/または PATH 上もしくは上記の解決方法による dotnet が必要です。Tier C はエディタアドオン（次の節）が必要で、それがインストールされていない、有効化されたエディタが稼働していない限り、5 つのエディタブリッジツールはすべて TIER_UNAVAILABLE で失敗します。期待される動作であり、バグではありません。エラーメッセージは、適用される 2 つの状況のどちらかをさます（docs/troubleshooting.md 参照）。

各ツールのティアは docs/tools.md を参照してください。

エディタアドオンのインストール（Tier C）

5 つのツール — editor_state、get_selected_node、live_scene_tree、open_scene_in_editor、execute_editor_script — は、プロセスを起動する代わりに、ループバック TCP ソケットを介して実行中の Godot エディタと通信します。これには、小さな GDScript エディタアドオンをターゲットプロジェクトにインストールして有効化する必要があります。インストールツールは存在しません。ユーザーの addons/ ディレクトリに書き込んだり project.godot を変更したりすることは、このプロジェクトのパス時の監禁規律が自動では行わないようにしているまさにそれだからです。これは一度限りの手動ステップです。

1. このリポジトリの addon/godot_mcp/ をターゲットプロジェクトの addons/ ディレクトリにコピーし、<project>/addons/godot_mcp/plugin.cfg に配置します。

2. プラグインを有効化します — エディタ上（プロジェクト設定 > Plugins > godot_mcp > Enable）または project.godot への直接追加のどちらかで:

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

3. そのプロジェクトの Godot エディタを起動（または再起動）します — ヘッドレスで十分です（--headless --editor --path <project>）。ディスプレイは不要です。アドオンは起動時に <project>/.godot/mcp_bridge.json へハンドシェイクファイルを書き出し、5 つのツールはそれを読み込んでブリッジのポートとセッションごとのトークンを特定します。

ヘッドレスエディタではエディタの選択状態が常に空になることに注意してください — これは想定どおりで、get_selected_node はエラーではなく通常の結果として「何も選択されていません」と報告します。

安全性とスコープ

• パス監禁（path jail）。 書き込む対象のパスはすべて — シーン、スクリプト、リソース、スクリーンショット出力 — を解決したときにプロジェクトルート内にあることが必須です。直接であれシンボリックリンク経由であれ、ルートから外れるパスは何かに触れる前に PATH_OUTSIDE_PROJECT で拒否されます。

• dry_run。 変更を行うすべてのツールは dry_run を受け取り、実際に書き込む代わりに統合差分（unified diff）を返します。変更を確定する前にプレビューとして使用してください。

• バックアップ保存はありません。 バージョン管理が undo システムです。これは意図的な単純化 — サーバー自体にはスナップショットやバックアップの仕組みはありません。プロジェクトがバージョン管理下にない場合は、変更を伴う呼び出しの前に dry_run を使うか、バージョン管理を開始してください。

• execute_editor_script はサンドボックスではありません。 稼働中のエディタプロセス内で任意の GDScript を、エディタ自身と同じ特権で実行します — 実行中のエディタの状態、開いているシーン、GDScript から到達できる追加のものを読み書きできます。エージェントにシェルを渡すときと同じように扱ってください。つまり、自分のプロジェクトで作業する信頼できるエージェントに適しており、信頼できない入力には適していません。

テスト

npm test

tsc --noEmit を tsconfig.json と tsconfig.test.json の両方に対して実行し、その後 Vue の Vitest スイート全体を実行します。実際上すべてのテストがパーサーレベルで、既知の Godot および MSBuild の出力をパーサーに通し、構造化された結果がと主張します。そのため Godot のインストールも .NET ツールチェーンもなくても実行でき、高速かつポータブルを維持できます（CI、コンテナ、そのどちらもインストールされていないラップトップ）。

GODOT_TEST_BINARY

2 つのブロックは注意が異なります。tests/integration/tier-b.test.ts は実際の Godot バイナリを操作します — ディスク上に一時プロジェクトを構築し、それに対して validate_script、check_shaders、run_project、godot_class_doc を起動します。なぜなら、パーサーを固定されたテキストに対して永遠にテストしても、ツール自身のプロセス生成・引数構築・ストリーム読み取りコードが実際のエンジンに対して動くことは証明できないからです。tests/integration/tier-c.test.ts はエディタブリッジツールに対して同じことをしますが、案外深く手法が異なります。実際の Godot エディタを長寿命のデタッチドプロセスとして起動し（エディタは自ら終了しない）、テストが失敗した場合も含めてその後に確実に回収する必要があります。

• 未設定（デフォルト）: 両ブロックは SKIPPED として報告されます。npm test の他の部分には影響しません。

• Godot 4.7+ バイナリのパスに設定 : 両ブロックともに対して実際にエンドツーエンドで実行されます。

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

このモノビルド/.NET ビルド、このブロックには不要です。C# 向けツール（build_csharp、run_tests）も触る場合は、PATH 上の dotnet が別途必要になります。これに相当するゲート変数は今はありません。GODOT_TEST_BINARY ブロックのテストでそれを必要とするものが、ないためです。

ドキュメント

• docs/tools.md — すべてのツールを領域別にまとめ、ティアと主な入力を記載。

• docs/troubleshooting.md — 実測された障害モードとその解決手段