godot-ai MCP server: install steps and which tools to let an agent write

To install the godot-ai MCP server, you install uv, copy the plugin into your project's addons folder and enable it in Godot 4.5 or later. According to the project's README, the plugin then starts the Python server and lets you connect an MCP client such as Claude Code or Codex from a dock inside the editor. A bigger decision is which of its 40-odd tools you let an agent call without asking you first.

The README covers installation, and the tool list lives in a separate document. This guide puts the two together and sorts the tools by how easy their changes are to reverse. Everything below is drawn from the project's own documentation.

What is godot-ai and what does it need?

The godot-ai README describes two parts: a Python MCP server and a Godot editor plugin. Together they connect MCP clients to a running editor. The project claims more than 120 operations across roughly 41 to 43 tools, which are listed in docs/TOOLS.md.

Prerequisites, per the README:

• Godot 4.5 or later, with 4.7+ recommended
• uv, the Python package manager, which runs the server
• An MCP client, such as Claude Code, Codex or Antigravity

The README describes the architecture like this. The client talks HTTP to the server on port 8000 at /mcp. The server talks WebSocket on port 9500 to the plugin. The plugin then uses Godot's EditorInterface and SceneTree APIs.

That last step matters for safety. The agent is not editing a copy or a sandbox. It works on whatever project you have open in the editor.

How do you install the godot-ai plugin and server?

Step 1: Install uv

The README tells you to install uv first, either with Astral's install script or with a package manager such as brew, apt, dnf or pacman. Astral publishes these script commands:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Step 2: Add the plugin to your project

The README gives three routes. It recommends the first:

1. Clone and copy. Clone the repository and copy plugin/addons/godot_ai into your project's addons/ folder.
2. Release ZIP. Download a release archive and extract the addon the same way.
3. Asset Library. Install from Godot's AssetLib.

git clone https://github.com/hi-godot/godot-ai.git
cp -r godot-ai/plugin/addons/godot_ai /path/to/your_project/addons/

The README warns that Asset Library updates lag behind GitHub. If an AssetLib install misbehaves, it suggests disabling the plugin and enabling it again.

Step 3: Enable the plugin

Open Project > Project Settings > Plugins and enable Godot AI. According to the README, the plugin starts the server or reuses one that is already running, and it shows connection status in a Godot AI dock.

A precaution before the first session

The README does not require this, but it is a sensible step. Put the project under version control and commit before you connect an agent, or use a throwaway copy for your first sessions. Several tools write straight to disk, as the sections below explain.

How do you connect an MCP client to godot-ai?

The dock lists supported clients, each with Configure and Remove buttons, plus a Configure all option. The README names Claude Code, Claude Desktop, Antigravity and Hermes Agent as auto-configured. It lists 17 or more others, including Codex, Cursor, VS Code and Zed.

The server URL is http://127.0.0.1:8000/mcp. For manual setup in Claude Code, the README uses claude mcp add with the HTTP transport. A third-party LobeHub listing shows the same form. LobeHub marks that listing as unvalidated, so treat the README as the authority.

claude mcp add --transport http godot-ai http://127.0.0.1:8000/mcp

The README also gives a config.toml entry for Codex that points at the same URL. Copy it from the README rather than retyping it.

On Windows, the README's troubleshooting section covers one known failure. uvx mcp-proxy can fail to start because installing pywin32 hits a file lock. The fix is in the README.

The README also includes sample prompts. Starting with a read, such as asking the agent to show the scene hierarchy, confirms the connection before anything changes. Save writes, such as creating a Camera3D, for after that check.

Which godot-ai tools are safe to let an agent run?

The docs do not sort tools by risk. The three tiers below are this article's analysis of TOOLS.md and the implementation plan.

Lower risk: reads

TOOLS.md lists editor_state, scene_get_hierarchy, node_get_properties and session_activate as the always-loaded core tools. The implementation plan describes read-only godot:// resources that mirror these cheap reads. Log reading, editor screenshots and text search add more read-only context.

Medium risk: undoable scene edits

The implementation plan says readiness gating and undo integration cover the current write surface. It cites single-undo behaviour on the camera, material and animation tools. On that basis, these look like the safest writes, because Ctrl+Z in the editor should revert them.

That conclusion rests on the docs alone. The plan describes undo as robust to history interleaving. That is the project's own design claim, and none of the sources cited here confirm it independently.

Higher risk: outside undo or hard to reverse

These tools change files or project-wide state:

• filesystem_manage write_text writes arbitrary text files. According to the plan, shaders are currently created this way.
• script_create and script_patch create and edit GDScript. The plan says script_patch shipped as an anchor-based replace.
• node_manage delete removes nodes.
• autoload_manage adds and removes autoload singletons.
• project_manage settings_set changes project settings.
• Input map and signal changes alter project wiring that other scenes depend on.

File writes land on disk, so editor undo is not a reliable way to roll them back. Source control is.

Execution tools

project_run plays the game. TOOLS.md notes that it autosaves in-memory MCP edits first unless you pass autosave=False, so a run can make unsaved agent edits permanent. editor_manage also includes quit and game_eval ops. The docs list both. Keeping them behind human approval is a judgement call: one closes your editor and the other runs code in the game.

For multi-step edits, TOOLS.md describes batch_execute as atomic, rolling back on the first error. That makes it a safer way to apply a sequence of scene changes than a string of separate calls.

How do you limit what the agent can do?

Drop whole tool domains

The implementation plan documents a --exclude-domains flag (for example audio,particle) and a matching dock UI. Both drop whole tool domains while keeping the four core tools. The plan says this was built for clients with tool caps (PRs #170 and #177).

According to the plan, non-search clients such as Antigravity hard-cap at around 40 tools. It also warns that large tool lists cost context and push models toward the wrong tool. Trimming unused domains therefore helps accuracy as well as safety. The same point comes up in our notes on what an AI-agent decompilation project shows about building agent tools.

Keep the server on loopback

The README says the server binds to 127.0.0.1 by default. An --allow-host option opens it to named CIDR ranges. The WebSocket bridge to the editor stays loopback-only because it is unauthenticated. Unless you need remote access, leave the default in place. If you do need it, the README suggests an SSH tunnel or Tailscale rather than exposing the server on your LAN.

Use your client's approval settings

Domain filtering works at the domain level, not per operation. For finer control, use your MCP client's own per-tool permission settings to require approval for the high-risk tools listed above. If you use Claude Code, our piece on its /doctor prompt audit and CLAUDE.md rules covers how to keep project instructions lean.

Can the test harness act as a guardrail?

The README describes an in-editor GDScript test framework, McpTestSuite, plus a test_run tool. An agent can write tests under res://tests/ and run them. The project's docs/testing.md has the details.

TOOLS.md adds two signals. Write responses for .gd files include a diagnostics field. Responses can also carry new_errors_since_last_call, which tells the agent to go and read the logs. The docs call it a doorbell, not a precise count.

One caveat from the docs: in headless sessions, parse failures may show up only in the write response's diagnostics. Tell the agent to check that field after every script write.

What are the limits, and who is godot-ai for?

The implementation plan is open about unfinished work:

• The release and install path is not yet marked complete for new users.
• Shader CRUD and animation_tree support are still pending.
• For some unsupported types, value coercion silently stores raw JSON rather than failing.

The silent JSON storage is the one to watch. A property can look set while holding the wrong kind of value.

Verdict, based on the docs: godot-ai suits solo developers who are comfortable with git and uv and want an agent working inside the live editor. It suits people who want a locked-down setup less well, because its built-in controls work at the domain level rather than per operation.

A reasonable starting policy:

1. Allow reads and undoable scene tools freely.
2. Require review for script_patch, write_text, deletes, autoloads, project settings, input map changes and game_eval.
3. Commit before every session.

For more engine guides see Godot, for other agent setups see Coding agents, and for more how-tos browse Experiments.