Godot MCP Server

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.

Most Godot MCP servers operate headlessly. They can create scenes, add nodes, attach scripts. That covers a lot of ground, but stops at the editor boundary. This one doesn't. 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.

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.

This server is built around a small set of composable, wide-reaching tools rather than a long list of narrow ones. Each tool is designed to teach agents how to use it well. Response messages include next steps, timing constraints, and cleanup reminders so agents stay on track without extra prompting.

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.

Quick Start

Prerequisites

• Node.js v18+
• Godot 4.x

Install via npm

npm install -g godot-mcp-runtime

Or clone from source

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

Configure Your MCP Client

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

If installed via npm:

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

If cloned from source:

{
  "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

This server intentionally keeps the tool count small. Each tool covers a broad surface area through operations and parameters, so agents spend less time finding the right tool and more time doing useful work. Tool descriptions and responses are written to guide agent behavior: what to call next, when to wait, and how to recover from errors.

Project

| Tool | Description | |------|-------------| | launch_editor | Open the Godot editor GUI for a project | | run_project | Run a project in debug mode and inject the MCP bridge | | stop_project | Stop the running project and remove the bridge | | get_debug_output | Read stdout/stderr from the running project | | list_projects | Find Godot projects in a directory | | get_project_info | Get project metadata and Godot version |

Runtime (requires run_project first)

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

| Tool | Description | |------|-------------| | take_screenshot | Capture a PNG of the running viewport | | simulate_input | Send batched input: key, mouse_button, mouse_motion, click_element, action, wait | | get_ui_elements | Get all visible Control nodes with positions, types, and text | | run_script | Execute arbitrary GDScript at runtime with full SceneTree access |

Scene: manage_scene

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

| Operation | Description | |-----------|-------------| | create | Create a new scene file | | add_node | Add a node to an existing scene | | load_sprite | Set a texture on a Sprite2D, Sprite3D, or TextureRect | | save | Re-pack and save the scene, or save-as with newPath | | export_mesh_library | Export scenes as a MeshLibrary for GridMap |

Node: manage_node

All mutation operations save automatically.

| Operation | Description | |-----------|-------------| | get_tree | Get the full scene tree hierarchy | | list | List direct child nodes of a node | | get_properties | Read a node's current property values | | update_property | Set a property on a node | | attach_script | Attach a GDScript to a node | | duplicate | Duplicate a node within the scene | | delete | Remove a node from the scene | | get_signals | List all signals on a node with their connections | | connect_signal | Connect a signal to a method on another node | | disconnect_signal | Disconnect a signal connection |

Project Settings: manage_project

Edits project.godot directly, no Godot process required. Safe to use even when autoloads are broken or headless operations are failing.

| Operation | Description | |-----------|-------------| | list_autoloads | List all registered autoloads with paths and singleton status | | add_autoload | Register a new autoload | | remove_autoload | Unregister an autoload by name | | update_autoload | Modify an existing autoload's path or singleton flag | | get_project_settings | Read settings from project.godot by section and key | | get_filesystem_tree | Get the project file tree with types and extensions | | search_in_files | Search for a string across project source files | | get_scene_dependencies | List all resources a scene depends on |

Validate: validate

Validate before attaching or running. Catches syntax errors and missing resource references before they cause headless crashes or runtime failures.

| Input | Description | |-------|-------------| | scriptPath | Validate an existing .gd file in the project | | source | Validate inline GDScript written to a temp file | | scenePath | Validate a .tscn file and check that all ext_resource references resolve |

Returns { valid, errors: [{ line?, message }] }. Fix reported errors and re-validate before calling attach_script or run_script.

UIDs: manage_uids (Godot 4.4+)

| Operation | Description | |-----------|-------------| | get | Get a resource's UID | | update | Resave all resources to update UID references |

Architecture

src/
├── index.ts                # MCP server entry point, routes tool calls
├── tools/
│   ├── project-tools.ts    # Project and runtime tool handlers
│   ├── scene-tools.ts      # Scene operations
│   ├── node-tools.ts       # Node operations
│   └── 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

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 manage_project to inspect and remove the failing autoload. It edits 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