MCP 服务器

godot-runtime-mcp

A TypeScript MCP server that lets AI assistants interact with the Godot 4.x game engine: not just editing files, but playing the game.

README

Godot Runtime 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, but 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, and that covers a lot of ground. But they stop 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. It presses keys, clicks buttons, reads what's on screen, and runs arbitrary code against the live scene tree.

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

What It Does

Headless editing: Create scenes, add nodes, set properties, attach scripts, manage UIDs. All the standard operations you'd expect, 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 and enables:

Screenshots: Capture the viewport at any point during gameplay
Input simulation: Batched sequences of key presses, mouse clicks and movement, UI element clicks by name or path, Godot action presses, 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 execute 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. This 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

Project

Tool	Description
`launch_editor`	Open the Godot editor for a project
`run_project`	Run a project and inject the MCP bridge
`stop_project`	Stop the running project and clean up 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, or just the Godot version if no project path is given

Runtime (requires `run_project` first)

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

Scene: `manage_scene`

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`	Save a scene, or save-as with `newPath`
`export_mesh_library`	Export scenes as a MeshLibrary for GridMap

UIDs: `manage_uids` (Godot 4.4+)

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

Node: `manage_node`

Operation	Description
`delete`	Remove a node from a scene
`update_property`	Set a property on a node
`get_properties`	Read node properties
`attach_script`	Attach a GDScript to a node
`list`	List child nodes
`get_tree`	Get the full scene tree hierarchy

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
├── 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 in the running game.

How the Bridge Works

When run_project is called:

mcp_bridge.gd is copied into the project directory
It's registered as an autoload in project.godot
The project launches with the bridge listening on UDP port 9900
Runtime tools send JSON commands to the bridge and await responses
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.