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, Cursor, Windsurf, VS Code, VS Code Insiders, Zed, Gemini CLI, Cline, Kilo Code, Roo 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"]
url = "http://127.0.0.1:8000/mcp"
enabled = true

Antigravity (~/.gemini/antigravity/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.

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>\AppData\Local\uv\cache\builds-v0\.tmpXXXXXX\Lib\site-packages\pywin32-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 plugin/addons/godot_ai/utils/uv_cache_cleanup.gd.
2. Auto-configure now writes UV_LINK_MODE=copy into the bridged entry's env block for every uvx-bridge client (Claude Desktop, Zed), 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 or Zed) 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%\uv\cache\builds-v0\.tmp* manually before retrying.

See CONTRIBUTING.md for development setup, testing, and PR guidelines.

Windows contributors: run .\script\setup-dev.ps1 in PowerShell. It builds test_project\addons\godot_ai as a directory junction — no admin rights and no Windows Developer Mode required.