Godot AI — The wait is over

Godot AI

CI codecov Godot Asset Store Discord

Godot AI connects Claude Code, Claude Desktop, Codex, Hermes Agent, and other MCP clients to a live Godot editor. Its ~43 tools and 120+ operations let AI assistants build scenes, edit nodes and scripts, wire signals, and configure UI, materials, animation, particles, cameras, and environments.

📦 Install from the Godot Asset Store or the legacy Asset Library. The Python server requires uv.

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

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

Quick Start

Prerequisites

  • Godot 4.5+ (4.7+ recommended)

  • uv (for the Python server)

    How to install uv (macOS / Linux / Windows / package managers)
    • 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"
    • Package managers: brew install uv, sudo pacman -S uv, sudo apt install uv, or sudo dnf install uv
    • More options: uv installation guide

  • An MCP client (Claude Code | Codex | Antigravity)

1. Install the plugin

From source (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.

Or from a Godot marketplace

Use the Godot Asset Store or the deprecated but still-active Asset Library. Marketplace releases may lag behind GitHub.

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.

Godot AI dock — Clients & Tools button highlighted

3. Connect your MCP client

The dock shows every supported client with Configure / Remove controls; use Configure all to set up every detected client. Supported clients include:

  • Claude Code, Claude Desktop, Antigravity, Hermes Agent, DeepSeek Harness
…and 17+ more clients

Codex, Grok Build, Cursor, Devin Desktop, VS Code, VS Code Insiders, Zed, Gemini CLI, Cline, Kilo Code, Roo Code, Zoo Code, Kiro, Trae, Cherry Studio, OpenCode, Qwen Code, Kimi Code, and Pi Agent.

Pi Coding Agent: Install an MCP extension that reads ~/.pi/agent/mcp.json; Pi has no built-in MCP support. See the Pi package gallery.

Most clients use godot-ai attach, a client-owned stdio bridge that starts or reuses the local backend, making tools available before Godot opens and across same-version editor restarts. The dock shows the configured transport and, when needed, a copyable manual command. Cherry Studio remains URL-only because it manages MCP servers inside the app.

Registering per-project instead of globally

CLI-configured clients use global user scope by default. To limit Godot AI to one project, set Editor Settings → Plugins → godot_ai/mcp_client_scope to project (or local, where supported), then press Configure again.

[!IMPORTANT] Configure removes existing godot-ai entries from every scope before writing the selected one. This can modify a checked-in .mcp.json, but never touches other server entries. Remove only affects the currently selected scope.

For project scope:

  • The client CLI resolves the project config against its own working directory. Launch Godot from the project directory so .mcp.json lands where expected.
  • Claude Code requires one-time approval: run claude in the project and accept the prompt.

Re-run Configure after changing ports, excluded domains, or plugin versions.

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

Block-world game scene built from MCP tool calls — voxel terrain, player, and UI

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

Manual Client Configuration

Prefer the dock-generated command: it selects a compatible launcher and includes the current version, ports, and excluded tool domains. Re-run Configure after any of those values change.

Claude Code:

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

Claude Desktop (claude_desktop_config.json):

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

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

On Windows, use the dock-generated entry so Store/MSIX paths and consoleless launching are handled correctly. Other clients expose their exact config in the dock's Run this manually panel.

Clients that support URL transport can instead use:

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

URL mode relies on the client's reconnect behavior and may require a client restart if Godot AI was not running at startup.

How It Works 
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 connects the editor to the Python MCP server over WebSocket; clients reach its tools and resources over HTTP or the attach stdio bridge.

Remote / LAN access (--allow-host)

The server binds to 127.0.0.1 by default. For LAN access, pass trusted IPs or CIDRs with --allow-host (repeat or comma-separate the flag):

godot-ai --allow-host 192.168.1.0/24

The editor WebSocket remains loopback-only. Allow only trusted ranges; prefer an SSH tunnel or Tailscale on untrusted networks.

Legacy mcp-proxy import errors

Update Godot AI, press Configure again, and restart the MCP client. This replaces old mcp-proxy entries with the current godot-ai attach launcher.

Windows: uvx or pywin32 install errors

Close Godot and the MCP client, reopen Godot, press Configure, then restart the client. Configure uses --link-mode copy, and the plugin cleans stale uv build directories to avoid Windows file-lock races. If the error persists, stop stray Godot AI Python processes before retrying.

Contributing

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

Windows: run .\script\setup-dev.ps1 in PowerShell; it creates the test project junction without admin rights or Developer Mode.

Telemetry & Privacy

Anonymous telemetry includes an installation UUID, event name, outcome, duration, platform, and version. It excludes code, scene contents, project/file names, and personal data; project-directory slugs are SHA-256 hashed.

Opt out by setting either environment variable to true:

export GODOT_AI_DISABLE_TELEMETRY=true
# or
export DISABLE_TELEMETRY=true

Opt-out creates no UUID, worker, or files. See telemetry and privacy details.

Star History

Star History Chart

License: MIT | Issues: GitHub

Project links

Data verified by PyPI on Aug 27, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

Owner

PyPI data
Data sourced directly from PyPI's database.

Credits

Author: Godot AI contributors

GitHub Statistics

Data verified by PyPI on Aug 27, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

Requires

Python >=3.11

Provides Extra

dev build

Tags

godot godot-engine mcp model-context-protocol ai llm gamedev editor-plugin

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

godot_ai-3.2.2.tar.gz (178.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

godot_ai-3.2.2-py3-none-any.whl (222.8 kB view details)

Uploaded Python 3

File details

Details for the file godot_ai-3.2.2.tar.gz.

File metadata

  • Download URL: godot_ai-3.2.2.tar.gz
  • Upload date:
  • Size: 178.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for godot_ai-3.2.2.tar.gz
Algorithm Hash digest
SHA256 e25a7149f17382de15b1b2874019ffe121aa6087d12141257ff79323d3ebd8a5
MD5 1a7db1c9515b55d7ee1db530ef8c82ad
BLAKE2b-256 492324e7b278e6ac63666984200135401732a63181927304f841d628d5d77de5

See more details on using hashes here.

Provenance

The following attestation bundles were made for godot_ai-3.2.2.tar.gz:

Publisher: release.yml on hi-godot/godot-ai

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file godot_ai-3.2.2-py3-none-any.whl.

File metadata

  • Download URL: godot_ai-3.2.2-py3-none-any.whl
  • Upload date:
  • Size: 222.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for godot_ai-3.2.2-py3-none-any.whl
Algorithm Hash digest
SHA256 6d2df1f7396680f07891c96d7c0d555015791b8ddce84e452629c4134e672091
MD5 a1de669aa08cff911e495e8a02428aa3
BLAKE2b-256 6bc911a3ad3a24fae5163165b01b520fcc68f60a7ea2fbd667d1e8610bc377b9

See more details on using hashes here.

Provenance

The following attestation bundles were made for godot_ai-3.2.2-py3-none-any.whl:

Publisher: release.yml on hi-godot/godot-ai

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

3.2.2 This release

2 files

3.2.1

2 files

3.2.0

2 files

3.1.5

2 files

3.1.4

2 files

3.1.3

2 files

3.1.2

2 files

3.1.1

2 files

3.1.0

2 files

3.0.7

2 files

3.0.6

2 files

3.0.5

2 files

3.0.4

2 files

3.0.3

2 files

3.0.2

2 files

3.0.1

2 files

3.0.0

2 files

2.9.2

2 files

2.9.1

2 files

2.9.0

2 files

2.8.5

2 files

2.8.4

2 files

2.8.3

2 files

2.8.2

2 files

2.8.1

2 files

2.8.0

2 files

2.7.6

2 files

2.7.5

2 files

2.7.4

2 files

2.7.3

2 files

2.7.2

2 files

2.7.1

2 files

2.7.0

2 files

2.6.1

2 files

2.6.0

2 files

2.5.13

2 files

2.5.12

2 files

2.5.11

2 files

2.5.10

2 files

2.5.9

2 files

2.5.8

2 files

2.5.7

2 files

2.5.6

2 files

2.5.5

2 files

2.5.4

2 files

2.5.3

2 files

2.5.2

2 files

2.5.1

2 files

2.5.0

2 files

2.4.4

2 files

2.4.3

2 files

2.4.2

2 files

2.4.1

2 files

2.4.0

2 files

2.3.2

2 files

2.3.1

2 files

2.3.0

2 files

2.2.3

2 files

2.2.2

2 files

2.2.1

2 files

2.2.0

2 files

2.1.2

2 files

2.1.1

2 files

2.1.0

2 files

2.0.1

2 files

2.0.0

2 files

1.5.1

2 files

1.5.0

2 files

1.4.4

2 files

1.4.3

2 files

1.4.2

2 files

1.4.1

2 files

1.4.0

2 files

1.3.3

2 files

1.3.2

2 files

1.3.1

2 files

1.3.0

2 files

1.2.10

2 files

1.2.9

2 files

1.2.8

2 files

1.2.7

2 files

1.2.6

2 files

1.2.5

2 files

1.2.4

2 files

1.2.3

2 files

1.2.2

2 files

1.2.1

2 files

1.2.0

2 files

1.1.0

2 files

1.0.2

2 files

1.0.1

2 files

1.0.0

2 files

0.4.3

2 files

0.4.1

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page