Godot AI: an MCP server that drives a live Godot 4.7 editor from Claude Code, Codex and Cursor

The gap Godot AI fills between an AI client and a running editor

Most AI coding tools see a project as text. They read files, propose diffs, and leave you to reopen the editor and check whether the scene still loads. Godot AI takes the opposite position: the editor is the thing being driven. Its README describes it as connecting "Claude Code, Claude Desktop, Codex, Hermes Agent, and other MCP clients to a live Godot editor", and the unit of work is a tool call against that editor, not a patch against a file.

The audience is narrow on purpose. You need Godot 4.7+ within the 4.x line for v4, uv for uvx, and an MCP client. If you write Godot code by hand and never wanted an agent in the loop, this adds a plugin, a Python process, and two authenticated local hops for no benefit. If you do want an agent to build a scene hierarchy, search for PackedScene files under a folder, or run a scene test suite, the README's own examples are exactly that shape.

How the MCP client, the Python server and the editor plugin talk to each other

The README gives the whole data flow in four lines. An MCP client calls `godot-ai attach` over stdio. The attach bridge forwards to a Python server that speaks authenticated HTTP on port 8000. That server talks to the Godot editor plugin over an authenticated WebSocket on port 9500. Both local hops use independent rotating capabilities, and the README states that neither falls back to unauthenticated access. The editor WebSocket stays loopback-only.

That design has a consequence worth stating plainly: a bare `http://127.0.0.1:8000/mcp` entry in a client config will not work, because it cannot authenticate or follow capability rotation. The dock-generated command is the supported path, and it carries the matching version, ports, resolver options, and excluded tool domains. Updates repin owned client entries automatically, which is why the README tells you to reconfigure after changing ports, telemetry preferences, or tool domains.

The dependency policy is unusually strict and the pyproject.toml says why in a comment: every behavior-defining distribution is pinned exactly and checked again at process startup. FastMCP, AnyIO, mcp, websockets and pydantic all carry exact pins. The stated reason is that V4's security limits touch narrow internals of FastMCP, Uvicorn and websockets, so a floating version could move a boundary the security model depends on. Dependency upgrades become a reviewed release change instead of something a resolver decides. That is a real cost: you cannot bump a transitive dependency yourself without stepping outside the supported configuration.

Installing the add-on and getting one tool call through

There is no package manager step for the plugin itself. The README points at GitHub Releases: pick a published version and follow that release's verification and installation instructions. The add-on belongs at `your-project/addons/godot_ai/`, with `plugin.cfg` inside that directory. The README is explicit that you should use the release's requirements and package rather than copying a source snapshot over an existing installation.

Once the files are in place, enable the plugin from the Godot menu. The README states the path as Project, then Project Settings, then Plugins, then Godot AI. If Godot AI does not appear in the plugin list, the README names the usual cause: the file is at `addons/plugin.cfg` instead of `addons/godot_ai/plugin.cfg`.

Enabling it starts the MCP server, and the Godot AI dock shows connection status. The next step is client configuration, done from the dock rather than by hand. The README describes pressing Configure next to a client, or Configure all for every detected client, and restarting the client if it does not notice the new configuration. The dock-generated command includes the matching version, ports, resolver options and excluded tool domains.

For a first real call, the README's examples are the honest starting point: ask for the current scene hierarchy, then ask for something that changes state, such as creating a Camera3D named MainCamera under /Main. The hierarchy request tells you whether the bridge is live before you let an agent modify a scene.

If you want the entry in the project rather than in global user scope, the README documents Editor Settings, then Plugins, then the `godot_ai/mcp_client_scope` setting, set to `project` or `local` where supported, followed by pressing Configure again. Note that Configure removes existing `godot-ai` entries from every scope before writing the selected one, so it can modify a checked-in `.mcp.json`. Launch Godot from the project directory so the client CLI writes configuration in the right place; Claude Code additionally needs a one-time approval from `claude` run inside that project.

The security boundary stops at the same user account

The rotating capabilities and the loopback-only WebSocket are the right defaults, and the README does not oversell them. It says directly that these controls do not protect against a compromised same-user process, and that Windows does not claim isolation from other local accounts. So the threat model is roughly: another machine on your network cannot reach the editor socket, and a client that only knows the HTTP port cannot authenticate. A process already running as you can do whatever you could do.

There is also a documented failure mode on Fedora Atomic desktops such as Bazzite, where `/home` is a symlink to `/var/home`. Godot AI 4.0.2 and earlier refuse any capability-directory path that passes through a link, so the server exits with `Last pending: capability_record`. The README says the next release follows a link when it is root-owned and sits in a root-owned directory other accounts cannot write, which is that layout. On 4.0.2 or earlier the workaround is the shell snippet the README prints, which resolves the capability directory to a real path, creates it with mode 700, and echoes the result:

export GODOT_AI_CAPABILITY_DIR="$(
  realpath -m "${XDG_CONFIG_HOME:-$HOME/.config}/godot-ai/capabilities"
)"
install -d -m 700 "$GODOT_AI_CAPABILITY_DIR"
printf 'Using: %s\n' "$GODOT_AI_CAPABILITY_DIR"

Telemetry is on by default and records an installation UUID, event, outcome, duration, platform and version. The README states it does not record code, scene contents, or project or file names, and that project-directory slugs are hashed before transmission. Opting out with `GODOT_AI_DISABLE_TELEMETRY=true` or `DISABLE_TELEMETRY=true` creates no telemetry UUID, worker, or files, which is a cleaner opt-out than most projects offer.

Where Godot AI is the wrong tool

The version floor is the first hard stop. Godot AI v4 requires Godot 4.7+ within the 4.x line. A project pinned to 4.2 or 4.3 cannot use it, and the migration guide for v3 to v4 is about moving an existing install forward, not about supporting older engines.

Client support is a list, not a promise. The README names Claude Code, Claude Desktop, Codex, Antigravity, Hermes Agent, DeepSeek Harness, Cursor and VS Code, and then carves out two exceptions: Pi Coding Agent needs an MCP extension that reads `~/.pi/agent/mcp.json`, and Cherry Studio is not supported in v4 at all, with stale v3 entries to be removed inside Cherry Studio itself. If your workflow is built on Cherry Studio, this release is not for you.

Topology matters too. The editor WebSocket is loopback-only, so an agent running in a container or on another machine has to run the bridge on the editor machine over SSH. That is documented, but it is extra plumbing, and it means a headless CI runner cannot simply point at a developer's editor. Finally, the exact pins described above mean that if you need a specific newer FastMCP or websockets version for an unrelated reason, you are outside the tested combination.

How it differs from a general Godot MCP server

The obvious alternative is a small, general-purpose MCP server for Godot: a single script that exposes a handful of file and project operations over stdio, with no editor plugin, no Python service, and no capability handshake. Those are simpler to reason about and simpler to install, often a single entry in a client config. The difference in approach is what the agent can see. A file-level server can read and write .tscn and .gd text; it cannot ask a running editor for the current scene hierarchy, and it cannot act on the editor's live state after a change.

Godot AI pays for that with process count and configuration surface: a Godot plugin, a Python server started by the plugin, an attach bridge over stdio, two ports, rotating capabilities, and a dock that owns client entries. The README's scale claim, "46 tools and 120+ operations", is part of the same trade. More surface means more that can be misconfigured, which is why the README keeps steering you back to the dock-generated command instead of a hand-written URL.

There is a middle path worth naming: use a file-level MCP server for refactors and text edits, and bring in Godot AI only when the task needs the live editor. Nothing in the README prevents running both, though you would be configuring two servers against the same project.

Maintenance, licensing and the cost of staying current

The repository is not archived and the last push was on 2026-09-10, with v4.0.4 released on 2026-09-09, v4.0.3 on 2026-09-08 and v4.0.2 on 2026-09-07. Releases are close together, and pyproject.toml declares version 4.1.0 with a Development Status of Production/Stable. The README also documents an update path inside the product: click Update in the Godot AI dock when an update is offered, and the final signed v3 release supports a one-click migration to v4 that restarts Godot once and migrates owned, supported client entries. It warns against extracting a new add-on over the old tree.

Upgrade cost is mostly client configuration, not code. Updates repin owned client entries automatically, but you must reconfigure after changing ports, telemetry preferences, or tool domains, and Configure rewrites `godot-ai` entries across scopes before writing the one you selected. If your `.mcp.json` is checked in, expect it to change.

The project is MIT licensed. That is permissive and short, which is the practical point here; it says nothing about the FastMCP, mcp, websockets or pydantic dependencies you will also be running, each of which carries its own licence and its own exact pin. Read those before shipping, and treat the pinned set as the supported configuration rather than a suggestion.

Editorial conclusion

Adopt Godot AI if you already run Godot 4.7+ and one of the listed MCP clients, and you want an agent working on a live editor rather than on files. Skip it if you are on Godot 3.x or an older 4.x, if you need Cherry Studio, or if the only machine that can run the bridge is not the machine running the editor. Verify first that the add-on sits at addons/godot_ai/plugin.cfg, that the dock's Configure button writes the entry into the scope you actually want, and that your client is listed as supported in the dock rather than assumed.

Frequently asked questions

Official sources

1. hi-godot/godot-ai on GitHub
2. Issues
3. License: MIT
4. README
5. Releases