# Godot Ai

> Production-grade MCP server and AI tools for the Godot engine. A Snap to install. Totally free and fun.

- **Type:** MCP server
- **Install:** `agentstack add mcp-hi-godot-godot-ai`
- **Verified:** Pending review
- **Seller:** [hi-godot](https://agentstack.voostack.com/s/hi-godot)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [hi-godot](https://github.com/hi-godot)
- **Source:** https://github.com/hi-godot/godot-ai

## Install

```sh
agentstack add mcp-hi-godot-godot-ai
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Godot AI

[](https://github.com/hi-godot/godot-ai/actions/workflows/ci.yml)
[](https://codecov.io/gh/hi-godot/godot-ai)
[](https://godotengine.org/asset-library/asset/5050)
[](https://discord.gg/FDZ5fr2QkP)

**Connect MCP clients directly to a live Godot editor** via the [Model Context Protocol](https://modelcontextprotocol.io/introduction). Over **120 ops across ~41 MCP tools** ([full list](docs/TOOLS.md)) 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](https://godotengine.org/asset-library/asset/5050) and the [new Godot Asset Store](https://store.godotengine.org/asset/dlight/godot-ai/)** — one-click install from Godot's **AssetLib** tab. You'll still need [uv](https://docs.astral.sh/uv/) for the Python server (see [Quick Start](#quick-start)).

> 💬 **[Join the Discord](https://discord.gg/FDZ5fr2QkP)** — 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.7+` recommended)
- [uv](https://docs.astral.sh/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](https://docs.astral.sh/uv/getting-started/installation/)
- An MCP client ([Claude Code](https://docs.anthropic.com/en/docs/claude-code) | [Codex](https://openai.com/index/codex/) | [Antigravity](https://www.antigravity.dev/))

### 1. Install the plugin

**Recommended — install from source** (always the latest):

```bash
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](https://github.com/hi-godot/godot-ai/releases/latest) and extract `addons/godot_ai` into your project's `addons/` folder.

Or via the Godot Asset Library

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**

…and 16+ more clients

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 find
a CLI, each dock row exposes a **Run this manually** panel with a copyable
snippet.

### 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](docs/TOOLS.md) for the full list of 120+ MCP tools and resources, grouped by domain.

Manual Client Configuration

**Claude Code**

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

**Codex** (`~/.codex/config.toml`)

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

**Antigravity** (`~/.gemini/antigravity/mcp_config.json`)

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

How It Works

```text
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.

Windows: uvx mcp-proxy won't start (pywin32 install fails)

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

```text
error: Failed to install: pywin32-311-cp313-cp313-win_amd64.whl (pywin32==311)
  Caused by: failed to remove directory `C:\Users\\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`](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:

```json
{
  "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.

Contributing

See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for development setup, testing, and PR guidelines. AI assistants should also read [AGENTS.md](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.

Telemetry & Privacy

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`:

```bash
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](docs/TELEMETRY.md).

---

## Star History

  

---

**License:** [MIT](LICENSE) | **Issues:** [GitHub](https://github.com/hi-godot/godot-ai/issues)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [hi-godot](https://github.com/hi-godot)
- **Source:** [hi-godot/godot-ai](https://github.com/hi-godot/godot-ai)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-hi-godot-godot-ai
- Seller: https://agentstack.voostack.com/s/hi-godot
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.