• 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"
• Prefer your package manager? uv is a popular open-source tool packaged in

most distro repos, so you don't have to pipe a script from the web:

• Arch: sudo pacman -S uv
• Debian / Ubuntu: sudo apt install uv (older releases: pipx install uv or the script above)
• Fedora: sudo dnf install uv
• macOS (Homebrew): brew install uv
• Other options: uv install docs

In Godot, open the AssetLib tab, search for Godot AI, click Download, then Install. Note: Asset Library updates lag behind GitHub, so this version may not be the most recent.

> 🚨 If installing from the Asset Library, most issues can be resolved by disabling and re-enabling the plugin in Project > Project Settings > Plugins.

Codex, Grok Build, Cursor, Devin Desktop (formerly Windsurf), VS Code, VS Code Insiders, Zed, Gemini CLI, Cline,
Kilo Code, Roo Code, Zoo Code, Kiro, Trae, Cherry Studio, OpenCode, Qwen Code,
Kimi Code.

Claude Code

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

Codex (~/.codex/config.toml)

[mcp_servers."godot-ai"]
command = "godot-ai"
args = [
  "attach",
  "--port", "8000",
  "--ws-port", "9500",
]
enabled = true
startup_timeout_sec = 60
tool_timeout_sec = 360

The dock chooses a compatible launcher automatically: a development venv,
an exact-version uvx --link-mode copy --from godot-ai==VERSION ... command,
or a matching system godot-ai install. Re-run Configure after changing
ports, excluded tool domains, or plugin versions so those launch arguments
stay synchronized.

On Windows, Configure writes a pythonw.exe launch (and, for uvx/system
tiers, a small stdio-preserving CREATE_NO_WINDOW bootstrap). This prevents a
terminal window from opening with Codex while keeping the MCP process attached
to Codex's stdin/stdout pipes. Do not simplify that generated entry back to a
console-subsystem python.exe, uvx.exe, or godot-ai.exe command.

Advanced fallback for clients intentionally kept in URL mode:

[mcp_servers."godot-ai"]
url = "http://127.0.0.1:8000/mcp"
enabled = true

URL mode depends on the client's own reconnect behavior. If Godot AI is not
running when the client starts, a client restart may still be required.

Grok Build (~/.grok/config.toml)

[mcp_servers.godot-ai]
url = "http://127.0.0.1:8000/mcp"
enabled = true

Or dock → Clients → Grok Build → Configure.

Antigravity (~/.gemini/config/mcp_config.json)

{
  "mcpServers": {
    "godot-ai": {
      "serverUrl": "http://127.0.0.1:8000/mcp",
      "disabled": false
    }
  }
}

MCP Client
   | HTTP (/mcp)
   v
Python Server (FastMCP)      port 8000
   | WebSocket               port 9500
   v
Godot Editor Plugin
   | EditorInterface + SceneTree APIs
   v
Godot Editor

The plugin starts or reuses the Python server, connects over WebSocket, and exposes editor capabilities as MCP tools and resources over HTTP.

The MCP server binds to 127.0.0.1 by default. To reach it from another
machine on your network (e.g. a remote coding agent), pass --allow-host
with one or more CIDRs or bare IPs (repeat the flag or comma-separate
values) when launching the server:

godot-ai --allow-host 192.168.1.0/24

This binds the HTTP transport off loopback and gates every request on the
real (unforgeable) socket peer address, so only hosts inside the named
range(s) get in — DNS-rebinding defenses (Origin / Host / Sec-Fetch-Site
checks) stay active. The plugin's WebSocket bridge to the editor always
stays loopback-only since it's unauthenticated. Only name ranges you trust;
prefer an SSH tunnel or Tailscale on untrusted networks.

Symptom (in your MCP client's server log):

error: Failed to install: pywin32-311-cp313-cp313-win_amd64.whl (pywin32==311)
  Caused by: failed to remove directory `C:Users<you>AppDataLocaluvcachebuilds-v0.tmpXXXXXXLibsite-packagespywin32-311.data`: ... os error 32

Cause: uv hard-links shared .pyd files (notably
pydantic_core/_pydantic_core.cp313-win_amd64.pyd) from archive-v0 into
each new builds-v0.tmpXXXXXX build venv. The running godot-ai Python
process has the same .pyd mapped via LoadLibrary — and because hard
links share the inode, Windows refuses to delete it under any path until
every process unmaps it. uv's post-install cleanup of the build venv then
dies on a stale lock; the misleading pywin32 mention is just the last
package in the resolution order, not the actual lock holder.

Mitigation in this plugin:

1. _stop_server and force_restart_server both call

McpUvCacheCleanup.purge_stale_builds() immediately after killing the
server children, while the .pyd is briefly unmapped. See
<code class="ra0-md-code">plugin/addons/godot_ai/utils/uv_cache_cleanup.gd</code>.

1. **Auto-configure now writes UV_LINK_MODE=copy into the bridged

entry's env block** for every uvx-bridge client (currently Claude Desktop),
telling uv to copy shared C extensions instead of hard-linking them.
That removes the reverse race where an MCP client spawns uvx mcp-proxy
while a server child still holds the .pyd. Existing entries written
by older plugin versions surface in the dock as drift (amber banner)
so a single Configure click rewrites them with the env pin.

The shape client_configure writes for Claude Desktop is now:

{
  "mcpServers": {
    "godot-ai": {
      "command": "uvx",
      "args": ["mcp-proxy==0.11.0", "--transport", "streamablehttp", "http://127.0.0.1:8000/mcp"],
      "env": { "UV_LINK_MODE": "copy" }
    }
  }
}

If you've already hit the lock on an older config, click Configure
on the affected uvx-bridge client (Claude Desktop) in the
godot-ai dock to rewrite the entry with the env pin, then quit and
reopen that client. If the lock persists (rare — pre-existing orphans
the cache sweeper couldn't reach), kill stray python.exe children
whose command line contains spawn_main(parent_pid=...) and delete
%LOCALAPPDATA%uvcachebuilds-v0.tmp* manually before retrying.

See CONTRIBUTING.md for development setup, testing, and PR guidelines. AI assistants should also read AGENTS.md.

Windows contributors: run .scriptsetup-dev.ps1 in PowerShell. It builds test_projectaddonsgodot_ai as a directory junction — no admin rights and no Windows Developer Mode required.

Godot AI ships anonymous, privacy-focused telemetry (no code, no scene contents, no project or file names, no personal data). Project-directory slugs are sha256-hashed before any event leaves your machine; only an anonymous installation UUID, the tool/event name, success/duration, and platform/version fields are sent.

Opt out by setting either environment variable to true:

export GODOT_AI_DISABLE_TELEMETRY=true
# or the cross-tool convention
export DISABLE_TELEMETRY=true

Opt-out is fully side-effect-free — no UUID generated, no worker thread, no files written.

Full details (what's collected, where data lives, how to self-host the endpoint): docs/TELEMETRY.md.