Install the Godot addon

The addon is the only part of the system that lives inside Godot. It is an EditorPlugin (@tool) that:

• dials the server's bridge listener (ws://127.0.0.1:9080 by default) and reconnects with backoff — launch order never matters
• routes the server's {id, command} envelopes to cmd_* handlers that call the Godot Editor API (one per operation, grouped by domain — see The Godot addon)
• shows a read-only status dock (connection state, project/scene/selected node, recent command outcomes with timing)
• registers the debugger plugin that powers live play-session inspection

Under the hood

The addon dials out to the server and reconnects, instead of hosting a server the MCP side connects to. The editor is the app that comes and goes, so this way launch order never matters. See Bridge & transport.

Option A: Godot Asset Store (easiest)

The addon is published as Godot Editor MCP - Addon on the Godot Asset Store. Install it into your project from there — or, inside Godot, open the AssetLib tab, search for Godot Editor MCP - Addon, and Install.

Option B: copy into your own project (from source)

cp -r godot-mcp/godot/addons/godot_mcp /path/to/your/game/addons/

Option C: use the bundled project

Open the godot/ folder of the godot-mcp checkout as a project in Godot 4.4+. This is a minimal project that exists so the addon is loadable and testable.

---

After installing by any method, enable the plugin: Project Settings → Plugins → Godot Editor MCP - Addon. The addon checks the editor version on enable and warns below 4.4.

Point the addon at your server

Same env var both sides — set it only if you deviate from the default:

Setting	Default	When to set
GODOT_MCP_BRIDGE_URL	ws://127.0.0.1:9080	Docker, remote server, or a non-default port

In the editor's environment (or via the project settings override), e.g. for Docker:

GODOT_MCP_BRIDGE_URL=ws://127.0.0.1:9080 godot --path /path/to/your/game

Verify

1. The status dock appears at the bottom of the editor (alongside Output/Debug): connection dot, server/Godot version, bridge URL, active scene (marked main.tscn ● while the editor holds unsaved edits — #591), selected node, a Last action row (the most recent undoable change — "create_node 'Player' (Ctrl+Z to undo)" — #590), a Playing row (the running scene + whether the agent's runtime probe is attached — #591), and the enabled toolsets (fed by the server, #592), and an outcome-bearing recent-command log (✓ success, ✗ with the error code — #589) with timing, a per-session count, and a Copy recent commands button (#594). Reconnect attempts and server notices (auth refusal, a peer replacement) share the same log (#593), so a flapping or taken-over link explains itself.
2. Green dot = the addon connected out to the server. The server and editor can start in either order — the addon reconnects automatically. If a second editor takes over the bridge, the first shows a distinct "Replaced by another editor" state (purple dot) instead of a misleading green — its commands now go to the other editor.
3. godot_health_check() from your agent returns {"bridge_connected": true, "version": "…"}.

Auto-refresh for external edits (optional)

The editor's own external-file detection is window-focus-driven — files changed by an agent, git, or any other tool while Godot is unfocused stay invisible until you click into the editor. All files written through godot-mcp tools already refresh the editor's filesystem view automatically; for edits made outside the MCP path, enable the opt-in auto-refresh:

GODOT_MCP_AUTO_REFRESH=1 GODOT_MCP_AUTO_REFRESH_INTERVAL=10 godot --editor

The MCP dock (bottom panel) has an Auto-refresh files checkbox — the runtime override of the env default. When on, the addon runs a periodic EditorFileSystem.scan() (never stacking a scan on an in-flight one) so external edits are picked up within one interval without focus.

Next: configure your MCP client.