Godot Editor MCP

A Godot editor plugin that lets AI agents drive a live editor over the Model Context Protocol.

What this addon is

Godot MCP is the Godot half of a two-part bridge. The other half is a companion MCP server (Python, published as godot-editor-mcp) that an AI client such as OpenCode, Claude, or any MCP-capable assistant spawns or connects to. This addon — a regular EditorPlugin that installs under res://addons/godot_mcp/ — joins the two: it turns the running editor into something an agent can inspect, edit, run, and verify.

Unlike editing project files blindly on disk, the agent works against the actual editor window the human has open — the same scene tree, the same undo stack, the same running game. Every change the agent makes is visible live and reversible with Ctrl+Z, and every read reflects the editor's real state rather than a stale file.

How the connection works

The addon embeds a WebSocketPeer client that dials out to the companion server's bridge listener on ws://127.0.0.1:9080 (configurable via the GODOT_MCP_BRIDGE_URL environment variable on both sides).

Dialing out rather than listening is deliberate:

• Start order never matters. Launch the editor before the server, or the server before the editor — whoever comes second simply connects.
• Restarts never wedge the connection. The addon reconnects automatically with exponential backoff, so a bounced server or a restarted editor recovers on its own.
• A second editor is handled honestly. If another editor instance takes over the bridge, the first shows a distinct "Replaced by another editor" state (purple dot) instead of a misleading green, and stops reconnecting.

All commands arrive as versioned JSON envelopes ({ id, command, params }) and are routed by a single command router to cmd_* handlers that call the Godot Editor API, returning a correlated { id, ok, result, error } response. The server initiates every command; the addon never acts unprompted.

The status dock

Enabling the plugin adds a read-only status panel at the bottom of the editor, alongside Output and Debug. It shows, at a glance:

• Connection state as a color dot (with the distinct "replaced" state)
• Server and Godot versions, and the bridge URL
• The active scene, with a ● dirty marker when unsaved
• The selected node in the editor
• The last undoable action (Ctrl+Z reverts it)
• Play-session and runtime-probe state
• The enabled toolsets
• A recent-command log with outcomes (✓ success, ✗ plus the error code; reconnect attempts and server notices share the same log), with a per-session count and a Copy recent commands button

The dock never mutates the project — it only reflects state.

What an agent can do once connected

The addon exposes a broad, purely generic Godot surface. Through it an agent can:

• Inspect the project, active scene, scene tree, selected node, node properties and groups — all read-only.
• Edit scenes — create, instance, duplicate, move, rename, and delete nodes; set properties with automatic Godot↔JSON type coercion; attach scripts; connect and disconnect signals; manage groups; save and reload scenes.
• Work with scripts — read, list, write, and patch GDScript, and check it for parse errors.
• Manage resources and project files — create resources, edit their properties, register autoloads, browse the filesystem, and read/write project settings.
• Author across every domain — physics bodies and collision, animation and state machines, 3D scenes and meshes, particles, navigation, audio buses, TileMap and TileSet data, themes and UI, shaders and visual shaders, and input maps.
• Play-test and verify — run the game headless or start an editor play session, simulate keyboard/mouse/action input, record and replay input, capture screenshots, take performance monitors, run GUT test suites, and fuzz the game with stress input. Debugger support adds breakpoints, stepping, stack frames, and expression evaluation against a paused game.
• Batch, analyze, and ship — find-and-edit across scenes, run static analysis (unused resources, signal flow, circular dependencies), and export builds from your export presets.

These capabilities are grouped into toolsets. Only core and inspection are enabled by default; the agent turns on exactly the toolsets a task needs via a single enable_toolset call, keeping its context small and its tool selection sharp.

Safety in the editor

The addon is built so a human can supervise an agent safely:

• Every mutation registers with EditorUndoRedoManager — any create, rename, delete, or property set is undoable with Ctrl+Z.
• Destructive handlers honor confirm — deletion and similar irreversible operations proceed only when the server's safety layer has confirmed them.
• Everything returned is JSON-safe — scene trees, node data, and properties serialize to plain JSON; Godot types such as Vector2/3, Color, Rect2, and NodePath are coerced by a single shared helper.
• Failures are structured — a handler error becomes an ok: false envelope with an error code and an actionable hint, never a raw engine trace.

All safety policy lives in the server, not the addon; this half simply performs the editor operations it is asked to, undo-tracked and serialized.

Live runtime support

Two optional pieces unlock inspection of a running game rather than the editor:

• A debugger plugin that captures the godot_mcp: debugger channel so the agent can see the live game tree and drive breakpoints.
• A runtime probe (mcp_runtime_probe.gd) that you add as an autoload in your game. It no-ops outside a debug session, so it is safe to leave enabled. With it, live input simulation, property monitoring, and UI element discovery all work; without it, those calls return a clear precondition failure instead of a silent no-op.

Requirements and setup

1. Install the companion server: uv tool install godot-editor-mcp (or run the Docker image). It listens for the editor on the bridge port.
2. Copy this addon into your project's addons/ folder, or install it from the Asset Library.
3. Enable it under Project → Project Settings → Plugins → Godot MCP.
4. Point your MCP client at the server. The editor connects itself.

Godot 4.4 or newer is required (the plugin checks the editor version on enable and warns if it is older; a few toolsets additionally refuse to enable on outdated editors).

The surface is game-agnostic — it knows Godot, not your game. No built-in game vocabulary, no genre assumptions. A tower-defense roguelite, a 3D platformer, and a visual novel all use the same generic tools.