Godot MCP Runtime — Godot 4 MCP server: what it does, how to install
Gives an AI agent control of a Godot 4 project with no editor open, plus screenshots, simulated input and live GDScript against the running game. Useful when the agent has to check its own change instead of handing it back to you.
claude mcp add --env GODOT_PATH=<GODOT_PATH> --env DEBUG=<DEBUG> --env GODOT_MCP_DISABLE_ELICITATION=<GODOT_MCP_DISABLE_ELICITATION> --env GODOT_MCP_STRICT=<GODOT_MCP_STRICT> --env GODOT_MCP_DISABLE_SECURITY=<GODOT_MCP_DISABLE_SECURITY> --transport stdio godot-mcp-runtime -- npx -y godot-mcp-runtimeWhat Godot MCP Runtime does
The server runs through npx with no addon in your project. On run_project it drops in an autoload called McpBridge, which listens on localhost over TCP and exposes the tools: viewport capture (a 960x540 preview inline and the full PNG saved to disk by default), key presses and clicks, a walk of the live scene tree to list visible Control nodes, and arbitrary GDScript with SceneTree access. Launch with profiling: true and it also collects Godot's own profiler data and ranks GDScript functions by cost.
Editing needs no editor window: scenes, nodes, properties, script attachment, signals, GDScript checks. For quiet runs pass background: true and the window moves off-screen and stops taking physical input. When something else starts the game, be it a CI job or your shell, call attach_project first so the runtime tools work against that session.
One limit matters. get_debug_output returns nothing in attached mode, because stdout and stderr only reach the server from processes it spawned itself. Need the log stream? Go through run_project. The bridge tears itself down on stop_project, detach_project, game exit or a dropped client, and its files sit in .mcp/godot-runtime/, which the server adds to .gitignore. It will not replace a playtest: an agent can confirm a scene loads and a button answers, but it cannot tell you whether the game feels right.
What it helps with
- confirm a scene loads without errors
- grab a viewport screenshot from a running game
- fire clicks and key presses at the UI and see what changed
- run GDScript against the live scene tree
- rank the most expensive GDScript functions with the profiler
Example prompts for the agent
- Run the Godot project in the background and screenshot the main menu
- Click the Start button through input simulation and show what changed on screen
- Attach to the game I already launched with
attach_projectand run a scene-tree script
How to install Godot MCP Runtime
Platform CLI
claude mcp add --env GODOT_PATH=<GODOT_PATH> --env DEBUG=<DEBUG> --env GODOT_MCP_DISABLE_ELICITATION=<GODOT_MCP_DISABLE_ELICITATION> --env GODOT_MCP_STRICT=<GODOT_MCP_STRICT> --env GODOT_MCP_DISABLE_SECURITY=<GODOT_MCP_DISABLE_SECURITY> --transport stdio godot-mcp-runtime -- npx -y godot-mcp-runtimeReplace <…> with your own values
Platform CLI
codex mcp add godot-mcp-runtime --env GODOT_PATH=<GODOT_PATH> --env DEBUG=<DEBUG> --env GODOT_MCP_DISABLE_ELICITATION=<GODOT_MCP_DISABLE_ELICITATION> --env GODOT_MCP_STRICT=<GODOT_MCP_STRICT> --env GODOT_MCP_DISABLE_SECURITY=<GODOT_MCP_DISABLE_SECURITY> -- npx -y godot-mcp-runtimeReplace <…> with your own values
Config file
{
"mcpServers": {
"godot-mcp-runtime": {
"command": "npx",
"args": [
"-y",
"godot-mcp-runtime"
],
"env": {
"GODOT_PATH": "<GODOT_PATH>",
"DEBUG": "<DEBUG>",
"GODOT_MCP_DISABLE_ELICITATION": "<GODOT_MCP_DISABLE_ELICITATION>",
"GODOT_MCP_STRICT": "<GODOT_MCP_STRICT>",
"GODOT_MCP_DISABLE_SECURITY": "<GODOT_MCP_DISABLE_SECURITY>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"godot-mcp-runtime": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"godot-mcp-runtime"
],
"env": {
"GODOT_PATH": "<GODOT_PATH>",
"DEBUG": "<DEBUG>",
"GODOT_MCP_DISABLE_ELICITATION": "<GODOT_MCP_DISABLE_ELICITATION>",
"GODOT_MCP_STRICT": "<GODOT_MCP_STRICT>",
"GODOT_MCP_DISABLE_SECURITY": "<GODOT_MCP_DISABLE_SECURITY>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e GODOT_PATH=<GODOT_PATH> -e DEBUG=<DEBUG> -e GODOT_MCP_DISABLE_ELICITATION=<GODOT_MCP_DISABLE_ELICITATION> -e GODOT_MCP_STRICT=<GODOT_MCP_STRICT> -e GODOT_MCP_DISABLE_SECURITY=<GODOT_MCP_DISABLE_SECURITY> godot-mcp-runtime npx -y godot-mcp-runtimeReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Godot MCP Runtime
How do I install Godot MCP Runtime in Claude Code?
Run claude mcp add godot-mcp-runtime -- npx -y godot-mcp-runtime. For environment variables use the other form, which passes --env values for GODOT_PATH, DEBUG, GODOT_MCP_DISABLE_ELICITATION, GODOT_MCP_STRICT and GODOT_MCP_DISABLE_SECURITY together with --transport stdio.
What does Godot MCP Runtime do?
It lets an agent edit a Godot 4 project headlessly and drive a running game: screenshots, simulated input, UI discovery, live GDScript, function profiling.
Does it leave anything in my Godot project?
The autoload is injected for the session and removed on stop, game exit or disconnect. Working files go under .mcp/godot-runtime/, and the server adds that folder to .gitignore.
