Godot AI
Godot AI connects Claude Code, Claude Desktop, Codex, Hermes Agent, and other MCP clients to a live Godot editor. Its 46 tools and 120+ operations let AI assistants build scenes, edit nodes and scripts, wire signals, and configure UI, materials, animation, particles, cameras, and environments.
Built in ~2 hours with Godot AI, without hand-written code or image generation — source
Quick Start
Requirements
- Godot 4.7+ within the 4.x line for Godot AI v4
- uv, which provides
uvxfor the Python server - An MCP client
Script languages. GDScript is fully supported: scripts written through
the tools are parse-validated, hot-reloaded, attached, and outlined. C# is
text-only: script_create / script_patch write .cs files and
script_manage(op="find_symbols") outlines them, but Godot AI does not build
.NET or report C# compiler errors. Build in the editor and inspect its Build
panel, or run dotnet build and inspect the terminal output.
Attaching a .cs needs a .NET-enabled editor build.
Details: C# support.
1. Install or update
New project: choose a published version from
GitHub Releases and follow its
verification and installation instructions. The add-on belongs at
your-project/addons/godot_ai/, with plugin.cfg inside that directory.
Use the release's requirements and package—not a source snapshot copied over
an existing installation.
Existing installation: click Update in the Godot AI dock when an update is offered. The final signed v3 release supports a one-click migration to v4; Godot restarts once and owned, supported client entries are migrated automatically. Do not extract a new add-on over the old tree. See the v3 → v4 migration guide for compatibility and recovery.
For development from source, use the contributor setup.
2. Enable the plugin
In Godot: Project → Project Settings → Plugins → Godot AI.
The plugin starts the MCP server and shows connection status in the Godot AI
dock. If it is missing from the plugin list, check that the file is at
addons/godot_ai/plugin.cfg, not addons/plugin.cfg.
3. Connect your MCP client
In the dock, press Configure next to your client, or Configure all for every detected client. If the client does not notice the new configuration, restart that client.
Supported clients include Claude Code, Claude Desktop, Codex, Antigravity, Hermes Agent, DeepSeek Harness, Cursor, VS Code, and Oh My Pi (manual configuration). The dock lists all supported clients and provides a Run this manually fallback where needed.
Use the dock-generated command: it includes the matching version, ports,
resolver options, and excluded tool domains. V4 uses godot-ai attach over
stdio; a bare http://127.0.0.1:8000/mcp entry cannot authenticate or follow
capability rotation. Updates repin owned client entries automatically;
reconfigure after changing ports, telemetry preferences, or tool domains.
Client exceptions: Pi Coding Agent needs an MCP extension that reads
~/.pi/agent/mcp.json. Cherry Studio is not supported in v4; remove stale v3
entries in Cherry Studio itself.
Per-project configuration
CLI-configured clients default to global user scope. Set Editor Settings →
Plugins → godot_ai/mcp_client_scope to project (or local, where supported),
then press Configure again.
Configure removes existing godot-ai entries from every scope before
writing the selected one. This can modify a checked-in .mcp.json, but does not
touch other server entries. Remove affects only the selected scope.
Launch Godot from the project directory so the client CLI writes configuration
in the right place. Claude Code also requires one-time approval from claude
run inside that project.
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."
A block-world game with a save system, built from a handful of prompts — source
How it works
MCP client
→ godot-ai attach (stdio)
→ Python server (authenticated HTTP, port 8000)
→ Godot editor plugin (authenticated WebSocket, port 9500)
Both local hops use independent rotating capabilities; neither falls back to unauthenticated access. The editor WebSocket stays loopback-only. An agent in a container or on another machine runs the bridge on the editor machine over SSH; see Agents on another machine or in a container.
These controls do not protect against a compromised same-user process. Windows also does not claim isolation from other local accounts. See the security model and package trust boundaries.
Telemetry and privacy
Usage telemetry records an installation UUID, event, outcome, duration, platform, and version—not code, scene contents, or project/file names. Project-directory slugs are hashed before transmission.
Opt out with GODOT_AI_DISABLE_TELEMETRY=true or DISABLE_TELEMETRY=true.
Opt-out creates no telemetry UUID, worker, or files.
Privacy details and editor settings.
Documentation and help
Bazzite / Fedora Atomic troubleshooting
On Bazzite and other Fedora Atomic desktops, /home is normally a symbolic
link to /var/home (the ostree layout). Godot AI 4.0.2 and earlier refuse
every capability-directory path that passes through a link, so on such a
system the server exits with Last pending: capability_record
(#993). In Godot AI 4.0.3 and later,
the server follows a link when it is root-owned and sits in a root-owned directory that
other accounts cannot write, which is exactly that layout; no configuration is
needed there.
On 4.0.2 or earlier, close Godot and your MCP client, then run this in a terminal as your normal user:
export GODOT_AI_CAPABILITY_DIR="$(
realpath -m "${XDG_CONFIG_HOME:-$HOME/.config}/godot-ai/capabilities"
)"
install -d -m 700 "$GODOT_AI_CAPABILITY_DIR"
printf 'Using: %s\n' "$GODOT_AI_CAPABILITY_DIR"
Launch both Godot and your MCP client from that terminal so the backend and
godot-ai attach inherit the same directory. A desktop launcher does not
automatically inherit a terminal's export; for persistent use, set the same
canonical path in the launch environment of both applications. Keep the
directory private to your user; do not copy capability tokens into client
configuration. This workaround is for Linux; GODOT_AI_CAPABILITY_DIR is not
supported on Windows.
Linux startup: Steam, Flatpak, and directory permissions
Godot AI 4.2.2 and later read process identity and listening-socket ownership
from /proc, so Steam and Flatpak runtimes do not need to provide ps, lsof,
or ss. These checks stay inside the editor's sandbox; host PIDs are not used
to authorize stopping a sandbox process. The backend launcher still needs to
be installed and executable within that environment.
Steam pressure-vessel can expose /home -> /var/home as a user-owned link.
Godot AI 4.2.2 and later accept root- or current-user-owned links beneath
protected parents and validates every target ancestor. Other-user ownership,
writable parents, and symlink loops remain rejected.
Some nested user namespaces expose host-root ancestors as an unmapped owner
(often UID 65534). Those paths still fail ownership verification. Do not chmod
system directories or treat UID 65534 as trusted to work around this; a usable
credential directory must have verifiable ownership and be accessible to both
the editor and its client bridge.
Use the explicit shared-directory guide
when the startup error names an untrusted ancestor owner. Resolving /home
with realpath alone does not fix an untrusted /var/home ancestor.
If the selected credential path has group- or world-writable ancestors (for
example 775 or 777), startup remains blocked. The plugin lists the existing
directories with problematic permissions before launching the server.
Review their ownership and intended sharing; if you own them and
shared write access is not intentional, chmod go-w /exact/directory removes
group/other write access from that directory. Do not use recursive chmod.
Godot AI does not change your home or config directory permissions itself.
Reference and support
- Tools, operations, and resources
- Community addons and custom tools
- Write and run tests for your game
- Client configuration details
- Upgrading from v3 and recovering interrupted migrations
- Changelog
- Contributing and development setup
- Discord for questions and showcases; GitHub Issues for bug reports
Star History
License: MIT
Release files for godot-ai 4.2.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| godot_ai-4.2.3.tar.gz | 215.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| godot_ai-4.2.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 481.4 kB
Release files / godot_ai-4.2.3.tar.gz
| Download URL | godot_ai-4.2.3.tar.gz |
|---|---|
| Size | 215.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d3af34cebef2d021fde381cd92a7c064f7c61f68ee9da7c91637fab0d070444b
|
|
BLAKE2b-256 checksum How to use checksums |
b64d85d2fcff1915e637af7dd3836bd380a257bdeb99173c14eefe452b77f5c8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 24, 2026.
Transparency logRelease files / godot_ai-4.2.3-py3-none-any.whl
| Download URL | godot_ai-4.2.3-py3-none-any.whl |
|---|---|
| Size | 265.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f68e46f34933e228b80adb7b841a442181372872adf4d5a4310222700d7368ea
|
|
BLAKE2b-256 checksum How to use checksums |
e0b4d5238ea7c2b0037fbe1cfa98628037785213d59972032a39d7037eb3cf2c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 24, 2026.
Transparency log
