Godot AI: an MCP server that drives a live Godot editor

The gap between an AI chat window and a running editor

Most code assistants see files. A Godot project is not just files. Scene trees, node properties, signal connections, and editor state live in a running process, and editing a .tscn by hand is a good way to break a scene you cannot see. Godot AI targets that gap: it connects MCP clients to a live Godot editor so an assistant can build scenes, edit nodes and scripts, wire signals, and configure UI, materials, animation, particles, cameras, and environments. The README puts the surface at 46 tools and 120+ operations, documented in docs/TOOLS.md. The audience is narrow on purpose. You need Godot 4.7+ within the 4.x line for Godot AI v4, uv installed so uvx can run the Python server, and an MCP client. If you edit Godot projects alone in a text editor and never open the editor while an agent works, this project has nothing to offer you.

Two hops, two rotating capabilities, and one loopback socket

The README gives the data flow as a four-stage chain: MCP client, then godot-ai attach over stdio, then a Python server speaking authenticated HTTP on port 8000, then the Godot editor plugin over an authenticated WebSocket on port 9500. Both local hops use independent rotating capabilities, and the README states plainly that neither falls back to unauthenticated access. The editor WebSocket stays loopback-only. That last detail matters more than it looks: it means the plugin is not reachable from another machine on your network, so remote work has to go through the documented bridge pattern, where an agent in a container or on another machine runs the bridge on the editor machine over SSH. The security model is documented rather than implied, and it comes with an explicit boundary: these controls do not protect against a compromised same-user process, and Windows does not claim isolation from other local accounts. Read that as the project telling you where its guarantees stop. If your threat model includes a hostile process running as you, this architecture does not address it.

Installing the add-on and enabling the plugin

The README is direct about installation: pick a published version from GitHub Releases 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. It also warns against copying a source snapshot over an existing installation. For an existing setup, you click Update in the Godot AI dock when an update is offered. The final signed v3 release supports a one-click migration to v4: Godot restarts once and owned, supported client entries are migrated automatically. The README says not to extract a new add-on over the old tree, and points to docs/v4-migration.md for compatibility and recovery. After the files are in place, you enable the plugin through Project, then Project Settings, then Plugins, then Godot AI. The plugin starts the MCP server and shows connection status in the Godot AI dock. The README names one specific failure here: if Godot AI is missing from the plugin list, check that the file is at addons/godot_ai/plugin.cfg and not addons/plugin.cfg. That single misplaced directory is the most common install mistake this project documents.

Configuring a client, and why the dock command is not optional

In the dock you press Configure next to your client, or Configure all for every detected client. If the client does not notice the new configuration, you restart that client. The README lists Claude Code, Claude Desktop, Codex, Antigravity, Hermes Agent, DeepSeek Harness, Cursor, and VS Code as supported, with a Run this manually fallback where needed. The instruction that carries the most weight is to use the dock-generated command, because it includes the matching version, ports, resolver options, and excluded tool domains. V4 uses godot-ai attach over stdio, and the README states that a bare http://127.0.0.1:8000/mcp entry cannot authenticate or follow capability rotation. That is a design consequence, not a bug: if the capability rotates and your client entry is static, the client loses the ability to authenticate. Updates repin owned client entries automatically, but you must reconfigure after changing ports, telemetry preferences, or tool domains. Two client exceptions are worth noting. Pi Coding Agent needs an MCP extension that reads ~/.pi/agent/mcp.json, and Cherry Studio is not supported in v4 at all, so stale v3 entries have to be removed inside Cherry Studio itself.

Per-project scope and the .mcp.json side effect

CLI-configured clients default to global user scope. To change that, you set Editor Settings, then Plugins, then godot_ai/mcp_client_scope, to project or to local where supported, and press Configure again. There is a side effect the README spells out rather than hides: Configure removes existing godot-ai entries from every scope before writing the selected one. That can modify a checked-in .mcp.json, though it does not touch other server entries. Remove affects only the selected scope. If your team commits .mcp.json, this behaviour is worth knowing before you press the button, because the write happens across scopes and a committed file can change as a result. The README also notes that you should launch Godot from the project directory so the client CLI writes configuration in the right place, and that Claude Code additionally requires one-time approval from claude run inside that project. Both are small operational details that decide whether the first connection attempt succeeds.

The Fedora Atomic symlink failure, and what it says about path handling

The most concrete limitation in the material is a documented failure, not a hypothetical one. On Bazzite and other Fedora Atomic desktops, /home is normally a symbolic link to /var/home because of the ostree layout. Godot AI 4.0.2 and earlier refuse every capability-directory path that passes through a link, so on such a system the server exits with Last pending: capability_record, tracked as issue #993. The next release follows a link when it is root-owned and sits in a root-owned directory that other accounts cannot write, which is exactly that layout, and the README says no configuration is needed there. On 4.0.2 or earlier the workaround is to close Godot and your MCP client, then run a shell block as your normal user that resolves the path with realpath -m, installs the directory with install -d -m 700, and prints it, exporting GODOT_AI_CAPABILITY_DIR to the resolved location. That is a real operational cost on a specific distro, and it is also a signal about how strictly the capability directory is validated. Strict validation is defensible for a directory that holds authentication material, but it means unusual filesystem layouts can block startup until you either upgrade or set the environment variable.

Telemetry, opt-out, and the licence

Usage telemetry 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. You opt out with GODOT_AI_DISABLE_TELEMETRY=true or DISABLE_TELEMETRY=true, and the README says opt-out creates no telemetry UUID, worker, or files, which is a stronger claim than simply not sending. Privacy details and editor settings live in docs/TELEMETRY.md. The project is MIT licensed, which in practice means you can read, modify, and redistribute the add-on and server, and that the authors disclaim warranty. This is a description of the licence text, not legal advice; if you plan to ship a modified copy inside a commercial product, read the MIT terms yourself and check whether any bundled dependency carries different terms, because the README does not enumerate them. Maintenance cost is mostly the version pin. The README ties Godot AI v4 to Godot 4.7+ within the 4.x line, and the client command embeds a matching version, so a Godot upgrade and a plugin upgrade are not independent events. The dock's Update button and the automatic repinning of owned client entries are the mechanisms that keep those two in step.

Where it fits, and what to check before you commit

The honest comparison is with doing the same work through file edits and editor scripting. A hand-written EditorScript runs inside Godot and can touch the same scene tree, but it is a one-shot script you write, run, and delete, and it has no client-side protocol, no capability rotation, and no per-client configuration. Godot AI's difference is the MCP layer: a persistent, authenticated channel that an assistant can call repeatedly across a session, with 46 tools and 120+ operations exposed and a dock that manages client entries for you. That is more moving parts, and more places for a misconfiguration to surface, which is why the README spends so much space on ports, scopes, and client exceptions. The trade is deliberate. You get an agent that can act on a live editor instead of guessing at text. You also inherit a Python server via uvx, two local ports, rotating capabilities, and a plugin that must sit at an exact path. If you already run Claude Code or Codex against your projects and you are on Godot 4.7+, the setup is a release download, a plugin toggle, and one Configure click. If you are on an older Godot, on Cherry Studio, or on a Fedora Atomic system you cannot update past 4.0.2, the friction lands before you see any benefit.

Editorial conclusion

Adopt Godot AI if you already run an MCP client and want an agent to edit scenes, nodes, scripts, and signals inside a live Godot 4.7+ editor, and you accept that a same-user process is outside the threat model. Do not adopt it if you need Cherry Studio support, if you are pinned to Godot 4.6 or earlier, or if your project lives on Fedora Atomic where /home is a symlink and you cannot update past 4.0.2. Before wiring a client, verify three things: that plugin.cfg sits at addons/godot_ai/plugin.cfg and not one level up, that you launched Godot from the project directory so the client CLI writes config in the right place, and that the command you paste came from the dock's Configure button rather than a hand-written http://127.0.0.1:8000/mcp entry, which the README says cannot authenticate or follow capability rotation.

Official sources

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