godot-mcp-loop

Edit, run, inspect and test Godot 4 projects from an MCP client. A TypeScript MCP server and a Godot editor addon let an AI coding agent change scenes/scripts, send gameplay input, inspect live state and replay checks. Work remains in normal Godot projects and resources.

日本語 · Get started · Architecture · Samples · Sample changes

The development loop

1. Edit: inspect a scene, change nodes, scripts or input settings.

2. Run: launch that project and send Godot action/key/mouse events.

3. Observe: read state, capture frames, inspect UI, physics and logs.

4. Check: compare expected values or replay YAML/JSON scenarios before making the next change.

The agent chooses and calls the tools; this is not a hosted service that automatically finishes a game. Game rules, artwork, sound, level design and playtesting remain authored work. Supported edits offer preview and undo; scene saving and file-backed operations have separate behavior.

Related MCP server: Godot MCP Flash

Six sample games

Native Godot captures from standalone projects, without the addon installed. The RPG frame is the prologue. Controls, project paths and original images.

All six run without an AI account or MCP setup. They show different uses of the same editing/observation tools; a fixture check is not a claim that an agent completed every game through ordinary play.

Try a sample

Use Node.js 20+ for the copy command and Godot 4.7 (tested with 4.7.2) to play. From a working folder, choose one of the six IDs above and a new/empty destination:

npx -y godot-mcp-loop@0.12.0 sample shooter ./my-shooter
godot --headless --path ./my-shooter --import
godot --path ./my-shooter

For agent editing/testing, explicitly install the addon from the same selected distribution and configure your client. Play alone does not need either step. The installer supplies its actual server executable; it does not register a client or restart an existing connection for you. Full setup guide.

How the pieces fit

• server/src/ exposes MCP tools, validates their input, connects to the selected project and runs scenarios.

• addons/mcp_loop/ edits through the Godot editor and forwards runtime requests through Godot's debugger.

• The game's runtime agent provides input, state, frame stepping, screenshots and logs. It adds no separate game-control listener.

• Optional server/authoring/ helpers process PNGs. Original image generation uses the client's separately authorized producer.

MCP client → stdio server → authenticated loopback WebSocket → Godot editor → debugger → running game

Architecture explains the two process layers, repository layout, data flow and persistence.

Capabilities and distribution status

Use the same selected distribution for the server and addon. Version labels alone do not prove equal contents; source checkouts can differ from published packages. doctor is a static CLI, not an MCP tool or runtime connection test. Tool reference · Artwork · Subtree construction.

Tools

Complete reference · Scenarios · Clients · Protocol.

Requirements and trust

• Node.js 20+ for the server; Godot 4.7 is the qualified target (tested with 4.7.2). The Logger API was introduced in 4.5; that does not qualify 4.5–4.6 for this distribution.

• Claude Code, Codex, Cursor, Claude Desktop, Hermes or another MCP client for agent control; none is needed just to play.

• Python 3.11+ / Pillow 13.0.0 only for optional PNG processing, not normal editing/play or node_add_tree. Dependencies are not installed automatically. C# script validation is not supported.

• One authenticated active MCP client per editor. Client setup/reconnection is explicit, not a side effect of copying a sample.

Loopback authentication and project-path guards are not an OS sandbox. Opening, validating or running a project can execute its code/plugins. Use trusted projects and client-side approvals. Undo is not a cross-file transaction; a missing response after dispatch does not prove that nothing changed. Inspect actual state before retrying. Security model.

Development

scripts/test-godot-unit.sh
cd server && npm ci
npm run typecheck && npm test
npm run build && npm run test:e2e
E2E_SAMPLES=1 npm run test:e2e

Windowed Linux checks need xvfb and E2E_GAME_WINDOW=1. Source authorities and generated copies are documented in sample changes; do not edit both independently. The default platformer scene remains an internal compatibility/test fixture and is not in the showcase. Release procedure.

License

MIT © OSHO