Godot AI

Godot AI

Connect MCP clients directly to a live Godot editor via the Model Context Protocol. Over 120 ops across ~39 MCP tools (full list) let AI assistants (Claude Code, Codex, Antigravity, etc.) build scenes, edit nodes and scripts, wire signals, and configure UI, materials, animations, particles, cameras, and environments.

🎉 Now on the Godot Asset Library and the new Godot Asset Store — one-click install from Godot's AssetLib tab. You'll still need uv for the Python server (see Quick Start).

💬 Join the Discord — questions, showcases, and contributor chat.

UI demo built in ~2 hours with zero coding, zero image gen, all programmatically drawn by Godot AI — source

Quick Start

Prerequisites

• Godot 4.3+ (4.4+ recommended)
• uv (for the Python server):
  • 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"
  • Other options: uv install docs
• An MCP client (Claude Code | Codex | Antigravity)

1. Install the plugin

Recommended — install from source (always the latest):

git clone https://github.com/hi-godot/godot-ai.git
cp -r godot-ai/plugin/addons/godot_ai your-project/addons/

Or download the latest release ZIP and extract addons/godot_ai into your project's addons/ folder.

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.

2. Enable the plugin

In Godot: Project > Project Settings > Plugins — enable Godot AI.

The plugin will automatically start the MCP server, connect over WebSocket, and show status in the Godot AI dock.

3. Connect your MCP client

The dock lists every supported client with a status dot and per-rowConfigure / Remove buttons, or press Configure all. Auto-configurecovers:

• Claude Code, Claude Desktop, Antigravity

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.

Server URL is always http://127.0.0.1:8000/mcp. If auto-configure can't finda CLI, each dock row exposes a Run this manually panel with a copyablesnippet.

4. Try it

• "Show me the current scene hierarchy."
• "Create a Camera3D named MainCamera under /Main."
• "Search the project for PackedScene files in ui/."
• "Run the scene test suite."
• "Build a voxel block-world game with a player, blocks to place and destroy, and save slots."

Demo gamelet with sophisticated save system built from a handful of Godot AI MCP prompts. Code and Godot project available free here.

Tools and resources: see docs/TOOLS.md for the full list of 120+ MCP tools and resources, grouped by domain.

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 (notablypydantic_core/_pydantic_core.cp313-win_amd64.pyd) from archive-v0\ intoeach new builds-v0\.tmpXXXXXX\ build venv. The running godot-ai Pythonprocess has the same .pyd mapped via LoadLibrary — and because hardlinks share the inode, Windows refuses to delete it under any path untilevery process unmaps it. uv's post-install cleanup of the build venv thendies on a stale lock; the misleading pywin32 mention is just the lastpackage in the resolution order, not the actual lock holder.

Mitigation in this plugin:

1. _stop_server and force_restart_server both callMcpUvCacheCleanup.purge_stale_builds() immediately after killing theserver children, while the .pyd is briefly unmapped. Seeplugin/addons/godot_ai/utils/uv_cache_cleanup.gd.
2. Auto-configure now writes UV_LINK_MODE=copy into the bridgedentry'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-proxywhile a server child still holds the .pyd. Existing entries writtenby 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 Configureon the affected uvx-bridge client (Claude Desktop or Zed) in thegodot-ai dock to rewrite the entry with the env pin, then quit andreopen that client. If the lock persists (rare — pre-existing orphansthe cache sweeper couldn't reach), kill stray python.exe childrenwhose 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.

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.

Star History

License: MIT | Issues: GitHub