Godot Agent Loop

Build it. Play it. Prove it.

An MCP automation loop for Godot 4.

Other integrations give agents tools. Godot Agent Loop gives them a feedback loop to author, run, observe, playtest, and independently verify Godot games:

author → validate → run → observe → playtest → verify → refine

Watch the 65-second demo · Read the exact run evidence · Inspect the resulting project

Quickstart

claude mcp add godot-agent-loop -- npx -y @beremaran/godot-agent-loop

Then point the agent at a project directory—or an empty directory—and describe the playable result. The default core surface is kept within the generated tool-surface budget. Use read-only godot_catalog to find and inspect a hidden capability, then godot_call to execute it. Runtime injection is transient; watched projects can use the optional persistent editor addon.

Using Cline, Cursor, or another MCP client? See Configuration.

Proof before claims

• The evaluation guide documents the pinned conformance, Inspector, Inspect AI, real-client, scorer, baseline, and paired-comparison lanes, including exactly which agent and model each lane uses.
• A retained representative real-Godot path is enforced in CI.
• Historically, a cold agent demonstrated MCP-only operation by building and independently verifying a playable win/lose game with zero human corrections in under seven minutes, using 103 MCP calls and no built-in tools. That launch pre-dates the lean surface reduction, which deliberately removed file, scene-authoring, and project-settings tools whose work host editors and shells do better; see the launch evidence and the changelog.
• Privileged reflection and code-execution groups are denied by default, and the editor provides a human Pause Agent control.

Support is deliberately bounded: Godot 4.7 is both the compatibility floor and the primary target. Editor attachment is verified on Linux CI and in a headed macOS 4.7.1 acceptance run; Windows retains the documented portable acceptance path but not an editor-UI claim. Full debugger automation, native extension builds, and unbounded engine control are not claimed. Details in the verified support boundary.

Highlights

• A lean task-oriented core — the default surface advertises 16 tools that cover the whole loop: catalog and dispatch (godot_catalog, godot_call), lifecycle (run_project, stop_project), the editor session and compound scene transactions (editor_session, editor_transaction), observation (game_screenshot, game_get_scene_tree, game_get_ui, game_get_node_info, game_get_errors, game_get_logs), structured interaction and waiting (game_scenario, game_wait_until), and independent verification (run_project_tests, verify_project).
• Everything else is one search away — 40 more tools remain callable through godot_catalog + godot_call: input primitives (mouse, keyboard, key-hold, drag, scroll, touch, gamepad), runtime reflection (privileged, opt-in), node and signal generics, observation extras (performance, visual regression, camera, audio), editor control, and ship tooling (export readiness, import pipeline, .NET, add-ons).
• Author with your own file tools — coding agents edit .gd/.tscn/.tres/project.godot directly and validate them with run_project_tests or headless checks; with an editor attached, editor_transaction applies undoable compound scene edits through EditorUndoRedoManager.
• Run and observe — launch the game, capture logs and errors incrementally, take screenshots, and run visual-regression comparisons with baselines, masks, and retained diffs.
• Playtest like a player — mouse, keyboard, key-hold, drag, scroll, touch, and gamepad input against the running game, composed deterministically with game_scenario.
• Verify independently — test runners for native/GUT/GdUnit4 (run_project_tests), bounded runtime evidence (verify_project), export checks (verify_export_readiness), and static integrity analysis (analyze_project_integrity).
• Reach into the runtime — with reflection and code-execution opted in, inspect and manipulate any node, signal, or property through game_eval and the generic node tools.
• Drive the editor — editor_session ensure discovers the matching project, editor_transaction applies reversible edits through EditorUndoRedoManager, and the Agent Activity dock replays the bounded correlated trace with a human Pause Agent lock.
• .NET / C# support — inspect, restore, build, and run .NET projects with a Godot.NET.Sdk matched to your installed Godot via verify_dotnet_project.
• Bounded by design — deterministic pagination and size caps on large responses, structured correlated diagnostics, and least-privilege security defaults.

Tool catalog

The full inventory—the 16 advertised core tools plus the hidden catalog of 40 more—lives in docs/tools.md.

Requirements

• Godot Engine 4.7 or later
• (Optional) .NET SDK 8.0+ and the Godot .NET (C#) build, only if you use verify_dotnet_project
• Node.js >= 22.0.0 (active LTS)
• An AI assistant that supports MCP (Claude Code, Cline, Cursor, etc.)

Godot compatibility policy

Development targets the latest stable Godot release. Godot 4.7 is the current compatibility floor and primary target, and CI covers that exact release. The floor may be raised when it blocks useful features or creates meaningful maintenance cost. In that case, the last compatible release remains available, and an older-version maintenance branch will be created only when user demand justifies maintaining it. Such a branch would receive critical fixes rather than new features.

Verified support boundary

Configuration

The quickstart npx command is all most setups need. The sections below cover other clients and a source checkout.

Interactive editor setup