Godot Mcp Runtime

Godot MCP Runtime

AI エージェントに Godot ゲームエンジンを操作するツールを提供する、軽量な MCP サーバーです。Godot 4.x プロジェクトの包括的なヘッドレス編集と、実行時の完全な制御を実現します。シーン、ノード、オートロード、検証に関する操作で、エンジンのごく特殊な機能を除くほぼすべてをカバーします。ランタイムブリッジでは、実行中のシーンツリーに対するスクリーンショットの撮影、入力シミュレーション、UI の検出、GDScript のライブ実行が可能です。

AI はゲームを書くだけでなく、その動作も確認できます。

• ヘッドレス編集：エディターウィンドウなしで、シーン、ノード、スクリプト、シグナルの編集や検証ができます
• 実行時制御：実行中のゲームに対するスクリーンショットの撮影、入力シミュレーション、UI の検出、GDScript のライブ実行、関数のプロファイリングができます
• 導入の負担なし：Godot アドオンも、プロジェクトへのコミットも不要で、終了時には自動でクリーンアップされます

アドオンは不要です。 実行時サポートを提供する多くの Godot MCP サーバーは Godot アドオンとして配布されています。アドオンはプロジェクトにインストールし、バージョン管理にコミットして、依存関係として管理する必要があります。npx を使えば、インストールもセットアップも不要です。

Playwright MCP の Godot 版と考えてください。ゲームでも同じことができます。プロジェクトを実行し、スクリーンショットを撮り、入力をシミュレーションし、画面に表示されている内容を読み取り、実行中のシーンツリーに対してスクリプトを実行します。エージェントは変更の確認をあなたに任せるのではなく、自ら変更内容を検証できます。

メモ

これはプレイテストの代替ではありません。人間だけが気づくような微妙な操作感の問題は検出できず、ゲームが楽しいかどうかも判断できません。できるのは、シーンが読み込まれること、ボタンが反応すること、値が更新されたこと、スクリプトがエラーなく実行されたことをエージェントが確認できるようにすることです。作業結果を確認できることは、AI 駆動のワークフローに不可欠です。

目次

• できること
• 他との比較
• クイックスタート
• ドキュメント
• 謝辞
• ライセンス

できること

このサーバーは、Godot を使った AI 支援ゲーム開発に最適なツールキットです。エージェントがシーン、ノード、スクリプトなどを作成できる、包括的なツール群を提供します。ランタイムツールセットを使えば、ゲームを実行してリアルタイムに操作することで作業内容を確認できます。また、プロジェクトに煩雑な依存関係を追加することもありません。

エージェント向けに構築。 各ツールは目的に特化しており、使い方を自ら説明します。失敗した場合は、エージェントが修正できるように応答で手順を示し、成功した場合は次のステップへ導きます。その結果、ユーザーが促さなくても、AI が行き詰まらずに自己修正できるようになります。

ヘッドレス編集。 シーンの作成、ノードの追加、プロパティの設定、スクリプトのアタッチ、シグナルの接続、GDScript の検証ができます。エディターウィンドウを開かずに、標準的な操作をすべて実行できます。

ランタイムブリッジ。 run_project または attach_project が呼び出されると、サーバーは McpBridge をオートロードとして注入します。これにより、localhost のみで待ち受ける TCP リスナーが起動します（どちらのモードでも、bridgePort を省略すると使用可能なポートが自動選択されます。特定のポートに固定するには bridgePort を指定してください）。次の機能が利用できます。

• スクリーンショット： ビューポートをキャプチャします。デフォルトでは、960x540 のプレビューをインラインで返し、フルサイズの PNG をディスクに保存します
• 入力シミュレーション： キーの押下、マウスクリック、マウス移動、名前またはパスによる UI 要素のクリック、Godot アクションイベント、フォーカス中の Control へのテキスト入力、時間指定の待機をまとめて実行します。各アクションでは、ヒットした Control、発生したシグナル、画面上で変更された内容を報告します
• UI の検出： 実行中のシーンツリーをたどり、表示されているすべての Control ノードについて、位置、種類、テキスト内容、無効状態を収集します
• スクリプトのライブ実行： ゲームの実行中に、SceneTree へ完全にアクセスしながら、任意の GDScript をコンパイルして実行します
• 関数のプロファイリング： 起動時に profiling: true を指定すると、Godot 独自のプロファイラーからデータを取得し、独自時間または包含時間の長い GDScript 関数を、ソース位置とフレームごとの平均とともにランキング形式で表示します

バックグラウンドモード。 run_project に background: true を渡すと、Godot ウィンドウは画面外（位置 (-9999, -9999)）に移動し、物理入力がブロックされます。ウィンドウはボーダーレスで、フォーカス不可かつマウス入力を透過します。プログラムによる入力、スクリーンショット、すべてのランタイムツールは通常どおり動作します。ウィンドウを表示したり操作したりする必要がない、自動化されたエージェント主導のテストに便利です。

手動アタッチモード。 MCP 以外の方法（CI パイプライン、外部デバッガー、独自のシェルなど）でゲームを起動する場合は、まず attach_project を呼び出します。Godot を起動せずにブリッジを注入してプロジェクトをアクティブとしてマークするため、手動でゲームを起動すれば、ランタイムツールがそのゲームに対して動作します。終了したら detach_project を使用してください。

重要

アタッチモードでは get_debug_output を利用できません。stdout と stderr が流れるのは MCP 自身が起動したプロセスのみです。そのため、Godot を外部から起動した場合、返却できるキャプチャ済みの出力はありません。デバッグストリームが必要な場合は run_project を使用してください。

ブリッジは自動的にクリーンアップされます。stop_project または detach_project の呼び出し時に加え、ゲームが自ら終了した場合、ブリッジ接続が切れた場合、またはサーバーがシャットダウンした場合（接続を閉じただけのクライアントの場合も含む）は、ツールを呼び出さなくてもクリーンアップされます。ブリッジの生成物はプロジェクト内の .mcp/godot-runtime/ に保存され、サーバーによって .gitignore に追加されます。オートロードや変更されたプロジェクトファイルが残ることはありません。

比較

Godot MCP の分野は、サーバーが 実行中の ゲームを操作できるか（ランタイム）、それともファイルの編集のみを行うか、そしてその実現にプロジェクトがどのようなコストを負うかという、2 つの軸で分かれています。実際のランタイム制御に対応するサーバーの多くは、インストールしてバージョン管理にコミットする Godot アドオン、またはダウンロードするカスタムエンジンとして提供されています。このサーバーはブリッジを一時的に注入し、シャットダウン時に削除するため、リポジトリに何も残さず、標準の Godot で実行中のゲームを完全に制御できます。

サーバー	実行中のゲームのランタイム制御	フットプリント	ライセンス	価格
Godot MCP Runtime	完全：スクリーンショット、入力、実行中のシーンツリー、スクリプト実行	ゼロ（npx、アドオンのコミット不要）	MIT	無料
Summer Engine	完全	カスタムエンジンのダウンロード＋サインイン	MIT のレイヤー／プロプライエタリーなエンジン	コアは無料、クラウドは有料
tugcantopaloglu/godot-mcp	完全	コミット済みのオートロードアドオン	MIT	無料
Godot MCP Pro	完全	コミット済みのエディターアドオン	プロプライエタリー	$15
GDAI MCP	エディター経由	コミット済みのエディターアドオン	プロプライエタリー	$19
Coding-Solo/godot-mcp	なし（起動＋デバッグ出力）	ゼロ（npx）	MIT	無料

実行中のゲームを完全に制御できるサーバーの中で、Godot MCP Runtime はフットプリントゼロのインストール（バージョン管理へのアドオンのコミット不要、カスタムエンジン不要、アカウント不要）を単一の npx コマンドで実現します。また、2026 年 2 月から、この一時的なオートロード型ランタイムブリッジを提供しています。すべての主張の出典を記載した約 20 サーバーの全体的な比較については、docs/comparison.md を参照してください。

クイックスタート

前提条件

• Node.js v20+
• Godot 4.x

以上です。Godot アドオンも、プロジェクトの変更も必要ありません。

MCP クライアントの設定

以下を MCP クライアントの設定に追加してください。Claude Code、Claude Desktop、Cursor、または MCP 互換クライアントで動作します。 AI アシスタントに check_project を呼び出すよう依頼してください。Godot のバージョン文字列（例：4.4.stable）が返されれば、接続され、動作しています。

npx によるインストール不要の方法（推奨）：

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "godot-mcp-runtime"],
      "env": {
        "GODOT_PATH": "<path-to-godot-executable>"
      }
    }
  }
}

または、グローバルにインストール：

npm install -g godot-mcp-runtime

{
  "mcpServers": {
    "godot": {
      "command": "godot-mcp-runtime",
      "env": {
        "GODOT_PATH": "<path-to-godot-executable>"
      }
    }
  }
}

または、ソースからクローン：

git clone https://github.com/Erodenn/godot-mcp-runtime.git
cd godot-mcp-runtime
npm install
npm run build

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["<path-to>/godot-mcp-runtime/dist/index.js"],
      "env": {
        "GODOT_PATH": "<path-to-godot-executable>"
      }
    }
  }
}

ヒント

pnpm を使いたい場合 3 つのインストール方法はいずれも pnpm で動作します。npx -y godot-mcp-runtime の代わりに pnpm dlx godot-mcp-runtime、グローバルインストールの代わりに pnpm add -g godot-mcp-runtime、ソースからのビルドの代わりに pnpm install && pnpm run build を使用してください。pnpm は npm のサプライチェーン攻撃に対する、より強固なデフォルト設定を備えています。pnpm のサプライチェーンセキュリティガイドを参照してください。

Godot が PATH に設定されている場合は、GODOT_PATH を省略できます。サーバーが自動検出します。

オプションの環境変数

すべて GODOT_PATH と同じ env ブロックに設定します。

変数	効果
DEBUG	"true" にすると、詳細な [DEBUG] ログが有効になります。

以下の 3 つのセキュリティゲートフラグは同じ軸を共有しており（全体像については docs/security.md を参照してください）、テーブルでは折り返しが見づらくなるため、リストにしています。

• GODOT_MCP_DISABLE_ELICITATION - "true" にすると、run_project と run_script の確認プロンプトを無効にします。クライアントでエリシテーションプロンプトを表示できない場合（自動的にキャンセルする Claude Desktop など）に使用してください。フェイルオープン動作となり、警告を表示してアクションを続行します。Tier 1 のセキュリティによるハードブロックは引き続き適用されます。
• GODOT_MCP_STRICT - "true" にすると、無人運用向けに、通常ならプロンプトが表示されるすべての操作をハード拒否します。両方が設定されている場合は、GODOT_MCP_DISABLE_ELICITATION より優先されます。
• GODOT_MCP_DISABLE_SECURITY - "true" にすると、run_script／run_project のセキュリティゲート全体を無効にします。スキャン、ブロック、エリシテーション、警告、監査サイドカーがすべて無効になり、Tier 1 も対象です。両方が設定されている場合は、GODOT_MCP_STRICT より優先されます。これを有効にするかどうかは人間が判断することです。エージェントはユーザーに代わって設定することを拒否してください。

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "godot-mcp-runtime"],
      "env": {
        "GODOT_PATH": "<path-to-godot-executable>",
        "GODOT_MCP_DISABLE_ELICITATION": "true"
      }
    }
  }
}

重要

Windows のパスに関する注意点。 GODOT_PATH には Godot のインストールフォルダーではなく、Godot の実行ファイル自体を指定する必要があります。JSON 内のバックスラッシュはエスケープするか、スラッシュに置き換えてください。

"GODOT_PATH": "D:\\Godot\\Godot_v4.4-stable_win64.exe"
// または同等の指定
"GODOT_PATH": "D:/Godot/Godot_v4.4-stable_win64.exe"

ラッパー .bat から変数を設定しても MCP サーバーには引き継がれません。上記のクライアントの env ブロックにパスを指定する必要があります。

ドキュメント

• docs/tools.md：カテゴリ別にまとめたツールの完全なリファレンス
• docs/tool-authoring.md：ツールの追加・変更に関する規約
• docs/architecture.md：ソースの構成、ブリッジのシーケンス図、ライフサイクルの手順、実行時のアーティファクトの動作
• docs/security.md：run_script／run_project のセキュリティモデル、ルール一覧、厳格モードの動作

謝辞

ヘッドレス Godot 操作の基盤として、Coding-Solo/godot-mcp を利用しています。

Claude Code を使用して開発しました。

ライセンス

MIT