Godot MCP Runtime

An MCP server that gives AI assistants direct access to a running Godot 4.x game. Not just file editing, not just scene manipulation. Actual runtime control: input simulation, screenshots, UI discovery, and live GDScript execution while the game is running.

When you run a project through this server, it injects a lightweight UDP bridge as an autoload, and suddenly the AI can interact with your game the same way a player would: press keys, click buttons, read what's on screen, and run arbitrary code against the live scene tree.

The distinction matters: the AI doesn't just write your game, it can check its work.

No addon required. Most Godot MCP servers that offer runtime support ship as a Godot addon — something you install into your project, commit to version control, and manage as a dependency. This server does none of that. The bridge script is injected on run_project and removed on stop_project. Your project files are left exactly as they were. All you need is Node.js and a Godot executable — no addon installation, no project modifications, no cleanup.

Think of it as Playwright MCP, but for Godot. Playwright lets agents verify that a web app actually works by driving a real browser. This does the same thing for games: run the project, take a screenshot, simulate input, read what's on screen, execute a script against the live scene tree. The agent closes the loop on its own changes rather than handing off to you to verify.

This is not a playtesting replacement. It doesn't catch the subtle feel issues that only a human notices, and it won't tell you if your game is fun. What it does is let an agent confirm that a scene loads, a button responds, a value updated, a script ran without errors. That's a fundamentally different development workflow, and it's what this server is built for.

Every operation is its own tool with only its relevant parameters — no operation discriminators, no conditional schemas. Each tool teaches agents how to use it through its description and response messages: what to call next, when to wait, and how to recover from errors.

What It Does

Headless editing. Create scenes, add nodes, set properties, attach scripts, connect signals, manage UIDs, validate GDScript. All the standard operations, no editor window required.

Runtime bridge. When run_project is called, the server injects McpBridge as an autoload. This opens a UDP channel on port 9900 (localhost only) and enables:

• Screenshots: Capture the viewport at any point during gameplay

• Input simulation: Batched sequences of key presses, mouse clicks, mouse motion, UI element clicks by name or path, Godot action events, and timed waits

• UI discovery: Walk the live scene tree and collect every visible Control node with its position, type, text content, and disabled state

• Live script execution: Compile and run arbitrary GDScript with full SceneTree access while the game is running

The bridge cleans itself up automatically when stop_project is called. No leftover autoloads, no modified project files.

Related MCP server: Godot MCP

Quick Start

Prerequisites

• Node.js v18+

• Godot 4.x

That's it. No Godot addon, no project modifications.

Configure Your MCP Client

Add the following to your MCP client config. Works with Claude Code, Claude Desktop, Cursor, or any MCP-compatible client.

Zero-install via npx (recommended):

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "godot-mcp-runtime"],
      "env": {
        "GODOT_PATH": "<path-to-godot-executable>"
      }
    }
  }
}

Or install globally:

npm install -g godot-mcp-runtime

{
  "mcpServers": {
    "godot": {
      "command": "godot-mcp-runtime",
      "env": {
        "GODOT_PATH": "<path-to-godot-executable>"
      }
    }
  }
}

Or clone from source:

git clone https://github.com/Erodenn/godot-mcp-runtime.git
cd godot-mcp-runtime
npm install
npm run build

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["<path-to>/godot-mcp-runtime/dist/index.js"],
      "env": {
        "GODOT_PATH": "<path-to-godot-executable>"
      }
    }
  }
}

If Godot is on your PATH, you can omit GODOT_PATH entirely. The server will auto-detect it. Set "DEBUG": "true" in env for verbose logging.

Verify

Ask your AI assistant to call get_project_info. If it returns a Godot version string (e.g., 4.4.stable), you're connected and working.

Tools

Project Management

Runtime (requires run_project first)

After calling run_project, wait 2-3 seconds for the bridge to initialize before using these tools.

Scene Editing (headless)

All mutation operations save automatically. Use save_scene only for save-as (newPath) or to re-canonicalize a .tscn file.

Node Editing (headless)

All mutation operations save automatically.

Project Config (no Godot process required)

These tools edit project.godot directly or read the filesystem. Safe to use even when autoloads are broken.

Validation: validate

Validate before attaching or running. Catches syntax errors and missing resource references before they cause headless crashes or runtime failures. Supports scriptPath, source (inline GDScript), scenePath, or a targets array for batch validation.

UIDs: manage_uids (Godot 4.4+)

Architecture

src/
├── index.ts                # MCP server entry point, routes tool calls
├── tools/
│   ├── project-tools.ts    # Project, runtime, autoload, filesystem, search, settings
│   ├── scene-tools.ts      # Scene creation, node addition, sprite loading, batch ops, UIDs
│   ├── node-tools.ts       # Node properties, scripts, tree, duplication, signals
│   └── validate-tools.ts   # GDScript and scene validation
├── scripts/
│   ├── godot_operations.gd # Headless GDScript operations
│   └── mcp_bridge.gd       # UDP autoload for runtime communication
└── utils/
    └── godot-runner.ts     # Process spawning, output parsing, shared validation helpers

Headless operations spawn Godot with --headless --script godot_operations.gd, perform the operation, and return JSON. Runtime operations communicate over UDP with the injected McpBridge autoload.

How the Bridge Works

When run_project is called:

1. mcp_bridge.gd is copied into the project directory

2. It's registered as an autoload in project.godot

3. The project launches with the bridge listening on 127.0.0.1:9900

4. Runtime tools send JSON commands to the bridge and await responses

5. When stop_project is called, the autoload entry and bridge script are removed

Files generated during runtime (screenshots, executed scripts) are stored in .mcp/ inside the project directory. This directory is automatically added to .gitignore and has a .gdignore so Godot won't import it.

Broken Autoloads

If any registered autoload fails to initialize (syntax error, missing resource, display dependency), Godot's headless process will crash before any operation runs. Use list_autoloads and remove_autoload to inspect and remove the failing autoload. These tools edit project.godot directly, with no Godot process involved.

Acknowledgments

Built on the foundation laid by Coding-Solo/godot-mcp for headless Godot operations.

Developed with Claude Code.

License

MIT