Godot AI

Connect MCP clients directly to a live Godot editor via the Model Context Protocol. Over 120 ops across ~43 MCP tools (full list) let AI assistants (Claude Code, Codex, Grok Build, Antigravity, Hermes Agent, 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.

Quick Start

Prerequisites

• Godot 4.5+ (4.7+ 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"

  • 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

• 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-row Configure / Remove buttons, or press Configure all. Auto-configure covers:

• Claude Code, Claude Desktop, Antigravity, Hermes Agent

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.

Most clients connect to http://127.0.0.1:8000/mcp. Claude Desktop and Codex are configured with the client-owned godot-ai attach stdio bridge instead, so they can discover the tools before Godot opens and keep using them across same-version editor restarts. If auto-configure can't find a compatible local launcher, each dock row exposes a Run this manually panel with a copyable snippet. Clients whose native configuration supports URL transport also show an advanced URL fallback.

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."

Tools and resources: see docs/TOOLS.md for the full tool, op, and resource list (~43 tools exposing 120+ ops, plus read-only godot:// resources), grouped by domain.

Testing: the plugin ships an in-editor GDScript test framework — your AI client (or you) can write McpTestSuite suites for your own game under res://tests/ and run them with test_run. See docs/testing.md.

Claude Code

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

Claude Desktop (claude_desktop_config.json)

Claude Desktop local configuration requires a launched stdio command. Per Anthropic's remote MCP guidance, it does not accept a remote url entry in claude_desktop_config.json; Claude's remote Connectors flow is cloud-brokered and cannot reach this loopback-only server. Use the dock-generated entry so the command is an absolute, GUI-safe launcher. Its non-Windows uvx shape is:

{
  "mcpServers": {
    "godot-ai": {
      "command": "/absolute/path/to/uvx",
      "args": ["--link-mode", "copy", "--from", "godot-ai==VERSION", "godot-ai", "attach", "--port", "8000", "--ws-port", "9500"]
    }
  }
}

On Windows, the dock also detects Store/MSIX AppData virtualization. When one Store package is installed, Configure uses its private LocalCache/Roaming path, creating the config there if necessary so a later copy-on-write cannot hide an entry written to conventional roaming. If the private file is new and the roaming config already exists, its full contents seed the private file before the godot-ai entry is merged; the roaming source remains byte-identical. Without a Store package it uses the conventional roaming config. Multiple matching Store packages fail with an actionable error instead of choosing one, and Configure never writes both.

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 Claude Desktop or Codex while keeping the MCP process attached to the client'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.

An older client configuration may launch mcp-proxy against an unbounded mcp>=1.17.0 dependency. mcp 2.x is incompatible with released mcp-proxy versions: 0.11.0 fails on streamablehttp_client, while 0.12.0 contains both incompatible imports and may report request_ctx first.

Preferred fix: update Godot AI, click Configure for Claude Desktop, and restart it. This replaces the legacy proxy entry with the current godot-ai attach launcher. As a temporary workaround, constrain the old uvx command with --with "mcp<2" before its mcp-proxy package argument.

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. Attach entries put --link-mode copy directly in the generated uvx arguments, telling uv to copy shared C extensions instead of hard-linking them. This works for configuration formats that do not support an env object and removes the reverse race where an MCP client starts its attach launcher while a server child still holds the .pyd.

The shape client_configure writes for Claude Desktop is now:

{
  "mcpServers": {
    "godot-ai": {
      "command": "/absolute/path/to/uvx",
      "args": ["--link-mode", "copy", "--from", "godot-ai==VERSION", "godot-ai", "attach", "--port", "8000", "--ws-port", "9500"]
    }
  }
}

The exact command may be an absolute uvx path or a Windows pythonw.exe bootstrap; use the dock-generated form rather than simplifying it. If you've already hit the lock, click Configure on Claude Desktop to rewrite its old mcp-proxy entry to the attach shape, then quit and reopen Claude Desktop. 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. AI assistants should also read AGENTS.md.

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.

Related MCP server: AI-godot-mcp

Star History

License: MIT | Issues: GitHub