Godot MCP Runtime is a lightweight, zero-footprint TypeScript MCP server designed to enable AI assistants to drive the Godot 4.x game engine. It provides comprehensive headless editing and full runtime control, enabling AI agents not only to write games but also to inspect the results of their work.
Purpose
This tool is aimed at AI-assisted game development scenarios, allowing AI agents to interact with the Godot game engine and perform operations such as scene editing and runtime control. It is designed as the "Playwright MCP for Godot," letting agents verify their own changes, for example confirming that a scene loads, a button responds, a value updates, or a script runs without errors, instead of leaving verification work to humans.
Main Capabilities
- Headless editing: Create scenes, add nodes, set properties, attach scripts, connect signals, and validate GDScript without an editor window.
- Runtime control: Through an injected bridge (the McpBridge autoload), it provides screenshots, input simulation, UI discovery, live GDScript execution, and function profiling.
- Screenshots: Capture the viewport, returning a 960x540 preview and a full PNG file by default.
- Input simulation: Batch key presses, mouse clicks, mouse movement, clicking UI elements by name or path, Godot action events, entering text into a focused Control, and timed waits. Each operation reports its behavior.
- UI discovery: Traverse the live scene tree and collect the position, type, text content, and disabled state of all visible Control nodes.
- Live script execution: Compile and run arbitrary GDScript while the game is running, with full SceneTree access.
- Function profiling: Set profiling: true at startup to capture Godot's own profiler, rank the most expensive GDScript functions by self or inclusive time, including source location and per-frame averages.
- Zero footprint: No Godot plugin is required, no project files are committed, and cleanup is automatic on shutdown. Bridge artifacts are located under the project at .mcp/godot-runtime/, and the server adds it to .gitignore.
- Background mode: When running run_project, pass background: true to move the Godot window off-screen (position (-9999, -9999)), physical input is blocked: no border, not focusable, mouse passthrough. Programmatic input, screenshots, and all runtime tools work as usual.
- Manual attach mode: When the game is launched by means other than MCP (CI pipeline, external debugger, your own shell), first call attach_project. It injects the bridge and marks the project as active, without launching Godot. When done, use detach_project. Note: in attach mode, get_debug_output is unavailable because stdout and stderr only flow through a process launched by MCP itself.
Usage
Use via npx with zero installation (recommended), or install globally, or clone from source. pnpm is supported. Configure an MCP client (such as Claude Code, Claude Desktop, Cursor, or any MCP-compatible client) and add the server configuration. If Godot is in PATH, GODOT_PATH can be omitted; the server will detect it automatically.
Optional environment variables include:
- GODOT_MCP_DISABLE_ELICITATION: set to "true" to disable confirmation prompts for run_project and run_script. Suitable for clients that cannot display prompts (such as Claude Desktop). Fail-open: the operation proceeds and a warning is issued. Tier 1 security hard blocks still apply.
- GODOT_MCP_STRICT: set to "true" to hard-reject any operation that would otherwise prompt, for unattended operation. When both are set, this takes precedence over GODOT_MCP_DISABLE_ELICITATION.
- GODOT_MCP_DISABLE_SECURITY: set to "true" to completely turn off the run_script / run_project security gate: no scanning, no blocking, no prompting, no warnings, no audit sidecar files—including Tier 1. When both are set, this overrides GODOT_MCP_STRICT. Enabling this option is a human decision, and the agent should refuse to set it on the user's behalf.
Windows path notes: GODOT_PATH must point to the Godot executable itself, not the installation folder. Backslashes in JSON must be escaped or replaced with forward slashes. Setting variables from a wrapping .bat will not propagate to the MCP server—the path must be in the client's env block.
When to use
- AI-assisted game development: let AI agents create scenes, nodes, and scripts, and inspect the work by running the game and interacting with it in real time.
- Automated agent-driven testing: testing when the window is invisible or non-interactive.
- When a CI pipeline or external debugger launches the game, use runtime tools via manual attach mode.
Limitations
- Not a substitute for game testing: it cannot catch subtle feel issues that only a human can notice, and it will not tell you whether the game is fun.
- get_debug_output is unavailable in attach mode.
- Requires a Godot 4.x project.
- Security gate behavior is controlled by environment variables, and some settings require a human decision.
More documentation
- docs/tools.md: complete tool reference, grouped by category
- docs/tool-authoring.md: standards for adding or modifying tools
- docs/architecture.md: source layout, bridge sequence diagram, lifecycle steps, runtime artifact behavior
- docs/security.md: run_script / run_project security model, complete rule catalog, strict mode behavior
This server is built on the headless Godot operation foundation of Coding-Solo/godot-mcp and was developed using Claude Code.
