Godot MCP Loop

godot-mcp-loop

AI エージェントが Godot 4 のゲームを編集し、自分で動作を確認できます。 検証ループ（変更 → 実行 → 観察 → 判定）に特化した MCP サーバーと Godot エディターアドオンです。

日本語 README · ツール · シナリオ · クライアント · セキュリティ · プロトコル

エージェントがシーンを編集できる Godot MCP サーバーは数多くあります。しかし、編集がうまくいったかどうかを確認できるものはほとんどありません。 godot-mcp-loop は、ゲームの起動、実際の入力の送信、条件が満たされるまでの待機、ライブ状態の読み取り、スクリーンショットの撮影、エラーの収集など、プレイテスター向けのツールキットをエージェントに提供します。さらに、失敗した値を含む合否レポートを返す宣言的なシナリオテストも備えています。編集は慎重に行われ、すべての変更を元に戻せるほか、プレビュー可能で、適用前に検証され、プロジェクト内にサンドボックス化されます。

エージェントにできること

godot_status                                    → editor connected, Godot 4.7.2, main.tscn open
script_write res://player.gd (dry_run)          → unified diff; compile errors with line numbers if any
script_write res://player.gd                    → written (undoable)
game_run                                        → game running, runtime connected
game_input [{action: move_right, hold_ms: 1000}]
game_wait_for Player position:x > 250           → met after 0.8 s
screenshot                                      → (image)
logs_read source=game min_level=error           → []
scenario_run res://tests/move_right.yaml        → PASSED (7/7 steps)

主な特長

• クローズドループ：game_run、game_input（実際のタイミングでアクション、キー、マウスを入力し、毎フレーム値を記録可能）、game_wait_for （毎フレーム確認し、タイムアウト時には最後の値を報告）、game_query、screenshot、logs_read。
• シナリオテスト：YAML/JSON のプレイテスト → ステップごとの合否、失敗時のスクリーンショット、ゲームエラー。詳細。
• 安全な編集：すべての編集は Godot の取り消し履歴を経由します。edit_undo は MCP 経由で行われた編集のみを元に戻します。 あらゆる操作で dry_run を利用でき、GDScript は書き込む前にコンパイルされ、プロパティ値は変更前に検証されます。
• サンドボックス化：localhost 専用のブリッジとセッションごとのトークンを使用します。res:// パスのみを許可し、.godot/、.git/ およびアドオンへの書き込みは許可しません。任意のコードを実行するツールはありません。セキュリティに関する注意。
• エラーでフリーズしない：Godot のデバッガーはスクリプトエラーが発生するとゲームを一時停止しますが、このアドオンはエラーを記録して処理を続けるため、エージェントはハングせずにエラーを確認できます。
• ゲーム内に追加ポートは不要：ゲームは Godot 独自のデバッガー接続を通じてエディターと通信します。
• 厳選された 41 個のツール：数百個ではなく、モデルが使いこなしやすい数に絞っています。

要件

• Godot 4.7（4.7.2 でテスト済み）。4.5～4.6 でも動作するはずです。アドオンには 4.5 で追加された Logger API が必要ですが、まだテストされていません。
• Node.js 20+
• MCP クライアント：Claude Code、Cursor、Claude Desktop、Codex、Hermes Agent など

インストール

Claude Code プラグインとして（Claude Code 2.1.275 以降。Godot プロジェクトのパスを一度尋ねます）：

/plugin install godot-mcp-loop --marketplace AI-osho/godot-mcp-loop

このプラグインは godot-loop MCP サーバーとエージェントスキルを登録します。npm パッケージを実行するため、手順の中でプロジェクトにコピーするアドオンはそのままにしてください（アドオンとサーバーのバージョンは一致している必要があります）。

npm を使用する場合（Node.js 20 以降）： npm を使用する場合（Node.js 20 以降）：

公式 MCP Registry に io.github.AI-osho/godot-mcp-loop として登録されています。 レジストリを参照できるクライアントなら、そこから追加できます。以下の手順も同じです。

1. アドオン — アドオンはサーバーと同じバージョンである必要があるため、サーバーにプロジェクトへのコピーと有効化を任せてください。

   npx -y godot-mcp-loop@latest install-addon /ABS/my-game --skill
   

   --skill を指定すると、エージェントスキルも追加されます（後述の手順 5）。このコマンドは、次に使用するバージョンを表示します。
2. クライアント — そのバージョンのサーバーを登録します。例：Claude Code

   claude mcp add godot-loop -- npx -y godot-mcp-loop@<version> --project /ABS/my-game
   

   その他のクライアントについては、docs/clients.md を参照してください。
3. Godot エディターでプロジェクトを開き、エージェントに godot_status を呼び出すよう依頼します。

ソースからインストールする場合：

1. アドオン — addons/mcp_loop をプロジェクトの addons/ フォルダーにコピーし、Project › Project Settings › Plugins › MCP Loop で有効にします。このプラグインはオートロード MCPLoopRuntime を登録します（エクスポートしたゲームでは無効です）。
2. サーバー —

   git clone https://github.com/AI-osho/godot-mcp-loop.git
   cd godot-mcp-loop/server && npm ci && npm run build
   

3. クライアント — 例：Claude Code

   claude mcp add godot-loop -- node /ABS/godot-mcp-loop/server/dist/index.js --project /ABS/my-game
   

   その他のクライアントについては、docs/clients.md を参照してください。
4. Godot エディターでプロジェクトを開き、エージェントに godot_status を呼び出すよう依頼します。
5. エージェントスキル（推奨）— .claude/skills/godot-mcp-loop をプロジェクトの .claude/skills/（または、すべてのプロジェクトで使用する場合は ~/.claude/skills/）にコピーします。このスキルでは、ループ、game_step による決定論的なチェック、シナリオのパターン、ピクセルアートについてエージェントに教えます。Agent Skills 形式に準拠しているため、スキルを読み込める他のエージェントも利用できます。

新しいゲームプロジェクトを作成する

scripts/new-game.sh ~/games/my-game --name "My Game" --register-claude

このコマンドは、アドオンを有効にした Godot プロジェクト、エージェントスキル、簡潔な AGENTS.md / CLAUDE.md ファイル、scenarios/ フォルダー、初回の git コミットを作成します。また、そのフォルダー用に Claude Code へ MCP サーバーを登録します（別の Claude Code 設定を使用する場合は --claude-config DIR を指定します）。その後、godot -e --path ~/games/my-game で開きます。

長時間のビルドでは、プロジェクトに PROGRESS.md（目標、状況、完了事項、次の作業、決定事項、既知の問題）も追加され、エージェントが内容を最新の状態に保ちます。また、Claude Code のプロジェクト設定（.claude/settings.json）も追加されます。セッション開始フックにより、起動時、再開時、/clear の実行後、コンテキストの圧縮後に、PROGRESS.md、直近のコミット、未コミットの変更がエージェントのコンテキストに表示されます。godot-loop のツールは権限の確認なしで実行され、破壊的なシェルコマンド（rm -rf、強制プッシュ、git reset --hard、git clean）は拒否されます。フォルダーの信頼確認に同意すると、Claude Code が許可ルールを適用します。

デモを試す

このリポジトリ自体が、小さなプラットフォーマー（examples/platformer、矢印キー＋Space）を含む Godot プロジェクトです。Godot で開き、サーバーにリポジトリのルートを指定して、エージェントに 「res://examples/platformer/scenarios/move_right.yaml で scenario_run を実行して」 と依頼します。続いて intentional_failure.yaml を試すと、失敗レポートを確認できます。

5分でわかる概要

1. プロジェクトフォルダーに アドオンをインストール します（addons/mcp_loopをコピーし、プラグインを有効にして、エージェントスキルを.claude/skills/に配置します）。

   cd my-game && npx -y godot-mcp-loop@latest install-addon . --skill
   

2. Godotでプロジェクトを開きます（4.5以降）：godot -e --path . — ブリッジはエディターとともに起動し、127.0.0.1でリッスンします。
3. MCPクライアントを接続 します。npx -y godot-mcp-loop@latest --project /absolute/path/to/my-gameを指定し、godot_statusを実行します。Godotのバージョン、プロジェクト、エディターで開いているシーンが報告されます。
4. 変更を1つ、チェックを1つ依頼 します：「レベルにコインを追加してから、scenario_run {"path": "res://scenarios/coins.yaml"}を実行してください」。ステップが失敗すると、観測値とスクリーンショットが返されます。
5. 記録します：「movie」には{}、「save_to」には"res://qa/evidence/tour"を指定して同じシナリオを実行し、qa/evidence/tour/movie.gifを開きます。実行全体と、主要なフレームのコンタクトシートを確認できます。

上級者向けサンプル

完全なゲームが5つ、examples/にあります。それぞれ、単一のプロンプトからAIエージェントがgodot-mcp-loopを通じて、コード、NES風のピクセルアート（image_write）、入力アクション、テストフック、回帰シナリオまでを一貫して生成したものです。その後、個別に検証されており、すべてのシナリオが合格し、ランダム入力で実行してもエラーは記録されません。

3Dサンプルはパッケージに同梱されているため、このリポジトリをクローンしなくても開けます：

npx -y godot-mcp-loop@latest sample marble-3d ./marble-3d
cd marble-3d && npx -y godot-mcp-loop@latest install-addon . --skill && godot -e --path .

これは3Dツールの開発時に使用したゲームです。7つのシナリオ（7_gap_needs_jump.yamlでは、ジャンプせずに隙間を越えられないことを検証します）、追従カメラ、コイン、チェックポイント、ライフ、制限時間付きのクリアが含まれています。npx -y godot-mcp-loop@latest sampleで同梱内容を一覧表示できます。

	ゲーム	生成元	サイズ	シナリオ
	落ちものブロック — 落ちものパズル：壁蹴り付きのSRS風回転、ゴーストピース、レベルとスコア、シードに基づくピース順	Claude Opus 5.5 (Claude Code)	381行	4
	縦スクロールシューティング — 5つのウェーブに登場する4種類の敵、3つの攻撃パターンを持つボス、爆発、スクロールする星空、11個のスプライト	Claude Opus 5.5 (Claude Code)	805行	4
	横スクロールアクション — 加速と可変ジャンプ、落とし穴と動く足場がある8画面分のステージ、踏みつけられる敵、コイン、ゴール、3層の視差スクロール、12個のスプライト	DeepSeek V4.1 Flash (Claude Code)	967行	4
	RPG「星剣のルカ」 — オリジナルの物語と登場人物が登場するNES風RPG：タイトルとプロローグ、グリッド移動、NPCとの会話、ランダムエンカウント、呪文、アイテム、逃走、レベルアップがある正面視点の戦闘、ボス、エンディング（日本語テキスト）	DeepSeek V4.1 Flash (Claude Code)	2,284行	6
	Marble Run — 最初の3Dサンプル：坂道や隙間を転がるビー玉、10枚のコイン、チェックポイントとライフ、追従カメラ、制限時間付きクリア、完全なHUD	DeepSeek V4.1 Flash (Claude Code)	676行	7

game_run {"scene": "res://examples/shooter/shooter.tscn"}を実行してプレイする（またはシーンを開いてF6を押す）と、scenario_run {"path": "res://examples/shooter/scenarios/4_boss_clear.yaml"}でチェックを再実行できます。すべてのチェックを実行するには、{"path": "res://examples/shooter/scenarios"}を指定します。操作方法と詳細：examples/README.md。

ツール

領域	ツール
ステータス	godot_status、project_info、project_list、project_connect（プロジェクトを切り替えます）
エディター	editor_launch（Godot を探してプロジェクトを開きます）、editor_quit
シーン	scene_open、scene_create、scene_save、scene_tree
ノード	node_add、node_delete、node_get、node_set
スクリプト	script_read、script_write、script_edit、script_attach
ファイルとアセット	file_write（YAML/JSON/テキスト）、image_write（ピクセルアート PNG）、input_action_set、project_setting_set（メインシーン、ビューポート、ストレッチ）
元に戻す	edit_undo
実行と観察	game_run、game_stop、game_query、game_ui_audit、game_in_view、game_ray、game_contacts、game_input、game_wait_for、game_set、game_call、game_pause、game_step、logs_read、screenshot
ビルド	project_export（シェルを使わず、プリセットから res://build/ にのみリリース用エクスポートを作成します）
判定	scenario_run（証拠フォルダー、movie → GIF とコンタクトシート）、test_run（GUT / GdUnit4 ユニットテスト）

完全なリファレンス：docs/tools.md。

ヘッドレス / CI

ゲームをウィンドウなしで実行するには、Project Settings › Editor › Run › Main Run Args に --headless を追加します（screenshot 以外はすべて動作します）。このリポジトリ独自の CI では、エンドツーエンドテストのために Linux 上でヘッドレスエディターとヘッドレスゲームを実行します。詳細は .github/workflows/ci.yml を参照してください。

開発

scripts/test-godot-unit.sh                   # GDScript unit tests (headless)
cd server && npm run typecheck && npm test   # TypeScript unit tests
npm run build && npm run test:e2e            # end-to-end against a real headless editor + game
E2E_GAME_WINDOW=1 npm run test:e2e           # same, with game windows (enables screenshot checks)

制限事項

• 一度に接続できる MCP クライアントはエディターごとに 1 つです（新しい接続が古い接続に置き換わります）。
• script_write は GDScript のみを検証します。独自に新しく定義した class_name を参照するスクリプトは、コンパイルチェックがやや厳密でない場合があります。
• C# プロジェクトはまだサポートされていません。

ライセンス

MIT © OSHO