Godot Agent
aigengame/godot-agent
CLI + MCP para IA controlar Godot com saída estruturada
Ver no GitHubUm servidor MCP e CLI orientado a agentes que permite que IA dirija a engine Godot para construir jogos, com saída estruturada e legível por máquinas. Fornece operações do Godot através de comandos CLI com JSON estruturado e schemas auto-descritivos, eliminando a necessidade de parsing de texto.
Instalação
npx convez-ai aigengame/godot-agent1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Geração automática de jogos por agentes de IA
- Integração de Godot em pipelines de desenvolvimento assistido por IA
- Operações headless em CI/CD para construção de cenas e assets
Veredito

Ferramenta especializada e bem arquitetada para automatizar fluxos Godot através de agentes. Ainda em fase inicial (Phase 1), mas com design sólido baseado em decisões arquiteturais documentadas. Ideal para quem quer integrar IA na pipeline de desenvolvimento de jogos.
README
A tradução para o português deste README ainda está na fila.
godot-agent (gda)

An agent-first CLI and MCP server that lets AI agents drive the Godot Engine to build games — with structured output built for programmatic consumption.
godot-agent lets AI agents drive the Godot engine through structured, machine-readable
operations rather than raw logs: an agent issues an operation and gets back a single clean
result it can act on, not prose it has to scrape.
It is delivered as three layers: gda, the agent-facing CLI that exposes Godot operations
with structured --json output and self-describing schemas; gda-mcp, a thin
Model Context Protocol server that turns those same
capabilities into MCP tools, derived mechanically from gda's schemas; and gda-daemon, a
long-lived process holding a persistent connection to a running engine to serve live operations
that a one-shot headless process cannot. gda lands first as a standalone headless CLI (Phase 1);
live operations follow through gda-daemon (Phase 2). See Architecture
for the full picture.
Why gda?
- 🤖 Agent-first, structured output. Every command supports
--jsonand emits exactly one result object on stdout. Engine noise and diagnostics are routed to stderr, so an agent never has to scrape prose. See the structured-output contract. - 📐 Model-driven & self-describing. Each command's input and output are defined as typed
models. The same model serializes
--jsontoday and will emit a machine-readable--schema(a JSON Schema contract) — so an MCP adapter can generate tool definitions mechanically instead of hand-maintaining them. (See ADR-0004.) - 🧩 Godot-native command surface. Commands are grouped by Godot domain object
(
gda scene create,gda node add, …) with a small, orthogonal verb vocabulary — zero learning cost if you already know Godot. (See ADR-0005.) - 📦 Standalone, no service required. The first delivery fulfils headless operations by
spawning one-shot
godot --headlessprocesses — nothing to install in the editor, no daemon to run. Live, stateful operations arrive later behind the same CLI. (See ADR-0001.) - 🛡️ Fails loudly, not silently. A missing or hung engine is bounded by a timeout and mapped to a non-zero exit with a clear diagnostic — never an indefinite hang or a raw traceback.
Project status
gdais in active early development (Phase 1). The architecture and contracts are settled (seeCONTEXT.mdanddocs/adr/), and the headless pipeline is live end-to-end. This README documents the working surface and the roadmap, and is explicit about which is which.
Working today
- ✅ A first working command surface: the
infometa command and the first domain command groups —gda scene create/gda scene get/gda scene list/gda scene deleteandgda node add/gda node list/gda node get/gda node set(ADR-0005). - ✅ The contract every shipped command carries: structured
--jsonoutput, model-derived--schemaself-description (ADR-0004), and structured{"error": {category, code, …}}failures with category-distinguishing exit codes. - ✅ The engine plumbing underneath: Godot binary resolution (flag / env var / default) and the
bounded one-shot
godot --headlessrunner with its sentinel output contract (ADR-0002).
On the roadmap (designed, not yet implemented)
- 🔜 The remaining domain command groups and commands: the rest of
node,script,project,resource,export, … - 🔜
gda-mcp, a thin Model Context Protocol adapter generated from--schema. - 🔜
gda-daemonfor live operations against a running engine (Phase 2).
The active backlog and per-command status live in the issue tracker — the headless increment is grouped under the Phase 1 — headless operations milestone. The command catalog maps the whole command surface (a non-binding feature map, not a status tracker); this section deliberately duplicates neither. See also the roadmap.
Architecture at a glance
gda is delivered bottom-up as three components and in two capability phases:
| Component | Role | Phase |
|---|---|---|
gda | The agent-facing Godot CLI — the bottom layer that exposes Godot with structured output | 1 |
gda-mcp | A thin MCP adapter that exposes gda's capabilities as MCP tools, derived from --schema | 1+ |
gda-daemon | A long-lived process holding a persistent connection to a running engine for live operations | 2 |
- Headless operations need no pre-existing engine state and are fulfilled by a one-shot
godot --headlessprocess (e.g. report version, create a scene, export). This is the basis of Phase 1. - Live operations require an already-running engine (live scene tree, runtime inspection,
UndoRedo, input simulation) and are served by
gda-daemonin Phase 2.
The vocabulary above is defined precisely in CONTEXT.md; the decisions behind it live
in docs/adr/.
Requirements
- uv — the Python toolchain/package manager used by this project.
- Python 3.13+ (uv can provision this for you).
- Godot 4.4+ —
gdatargets Godot 4.x with a minimum of 4.4; 4.6 is the tested baseline. 3.x is not supported. (See ADR-0003.)
Installation
gda is not yet published to a package index; install it from source with uv.
git clone https://github.com/aigengame/godot-agent.git
cd godot-agent
uv sync # create the environment and install dependencies
uv run gda --help
To install gda as a standalone CLI on your PATH:
uv tool install .
gda --help
Quick start
Point gda at your Godot binary and ask for the engine version:
# Use the GDA_GODOT environment variable (or the --godot flag, or the default path)
export GDA_GODOT="/path/to/Godot"
gda info --json
{"major":4,"minor":6,"patch":3,"hex":263683,"status":"stable","build":"official","hash":"7d41c59c457bd5a245092b4e7eb2d833e3b3f8c3","string":"4.6.3-stable (official)","timestamp":0}
Without --json, gda info prints the human-readable version string (4.6.3-stable (official)).
All engine and script diagnostics go to stderr, so stdout is always clean JSON you can pipe:
gda info --json | jq .major # → 4
Create a scene headlessly and read its structured tree back:
gda scene create game/main.tscn --root-type Node2D --json
# {"path":"game/main.tscn","root_name":"main","root_type":"Node2D"}
gda scene get game/main.tscn --json
# {"path":"game/main.tscn","root":{"name":"main","type":"Node2D","children":[]}}
Add a node into that scene and verify it landed — nodes are addressed by their path relative to
the scene root (. is the root itself):
gda node add game/main.tscn --type Sprite2D --name Hero --json
# {"scene_path":"game/main.tscn","path":"Hero","name":"Hero","type":"Sprite2D","script_class":null}
gda node list game/main.tscn --json
# {"scene_path":"game/main.tscn","root":{"name":"main","type":"Node2D","path":".","children":[{"name":"Hero","type":"Sprite2D","path":"Hero","children":[]}]}}
Read a node's properties as typed JSON, set one (the CLI value is coerced to the property's declared
Godot type), and verify the change round-trips via get:
gda node set game/main.tscn --node Hero --property position --value 10,20 --json
# {"scene_path":"game/main.tscn","path":"Hero","property":"position","type":"Vector2","value":[10.0,20.0]}
gda node get game/main.tscn --node Hero --json
# {"scene_path":"game/main.tscn","path":"Hero","name":"Hero","type":"Sprite2D","properties":[…,{"name":"position","type":"Vector2","value":[10.0,20.0]},…]}
Enumerate a project's scenes, then delete one — scene list walks the project's res:// tree, so it
needs a project context (--project, $GDA_PROJECT, or a cwd that is a project):
gda scene list --project game --json
# {"scenes":[{"path":"res://main.tscn","root_name":"main","root_type":"Node2D"}]}
gda scene delete res://main.tscn --project game --json
# {"path":"res://main.tscn","root_name":"main","root_type":"Node2D"}
Usage
Command surface
gda commands are grouped by Godot domain object and use a small, consistent verb vocabulary,
so the same verb means the same thing in every group:
gda <group> <command> [options] # domain commands, e.g. gda scene create
gda <meta-command> [options] # meta commands about gda/the engine, e.g. gda info
| Verb | Meaning |
|---|---|
create / delete | Make / remove a standalone entity (scene, script, resource) |
add / remove | Add / remove a sub-entity within a container (node → scene) |
get / list | Read one entity / enumerate many |
set | Mutate a property |
| domain verbs | play, run, export, import, … kept with their natural meaning |
The surface grows one vertical slice at a time;
gda --helplists what is installed, and the active backlog / per-command status lives in the issue tracker (the Phase 1 milestone). The taxonomy and naming rules are specified in ADR-0005.
Global flags
| Flag | Description |
|---|---|
--json | Emit the result as a single JSON object on stdout. Without it, commands print a concise human-readable rendering. |
--schema | Emit the command's input/output JSON Schema contract (no Godot spawned). |
--godot | Path to the Godot binary (overrides $GDA_GODOT and the default). |
--project | Godot project directory for res:// resolution (overrides $GDA_PROJECT; defaults to the current directory if it is a project). Domain commands only. |
--help | Show usage for gda or any command. |
Configuration
gda resolves the Godot binary in this order (highest precedence first):
- The
--godot <path>flag. - The
GDA_GODOTenvironment variable. - A default development path —
~/Applications/Godot.app/Contents/MacOS/Godot(macOS). On other platforms, setGDA_GODOTor pass--godot.
gda info --godot "/Applications/Godot.app/Contents/MacOS/Godot" --json
Project context
Domain commands resolve a Godot project so that res:// paths and a scene's
inter-resource references resolve deterministically, in this order (highest precedence first):
- The
--project <dir>flag. - The
GDA_PROJECTenvironment variable. - The current directory, when it is a Godot project (contains
project.godot).
A named directory must be a project, or gda reports it as an error. When none resolves, gda
runs projectless — only filesystem paths (absolute or cwd-relative) resolve, not res://.
Path normalization happens once at the CLI layer: res:// / user:// / uid:// pass through to
the engine; filesystem paths get ~ expanded. See
ADR-0006.
gda scene get res://main.tscn --project ~/game --json
The structured-output contract
Headless Godot interleaves its banner, warnings, and print() output into stdout. gda solves this
with a sentinel contract (ADR-0002):
-
The GDScript payload emits exactly one result, wrapped in unique sentinels on stdout:
<<<GDA:RESULT>>>{ ...json... }<<<GDA:END>>> -
It routes all of its own diagnostics to stderr; stdout carries nothing but the contract.
-
gdaextracts and parses only the bytes between the sentinels, ignoring the surrounding engine noise, and surfaces stderr for inspection.
This is what makes gda's output safe to consume programmatically, and it generalizes to the
per-message protocol the daemon will use in Phase 2.
Development
uv sync # set up the environment
uv run pytest # run the full suite (includes e2e tests against a real Godot)
uv run pytest -m "not e2e" # unit tests only (no Godot binary required)
uv run pytest -m e2e # only the end-to-end tests (needs Godot 4.4+ on this machine)
The e2e tier runs by default with uv run pytest, and fails loudly — naming the
resolved path and how to fix it — if no Godot binary is found there, rather than skipping.
Deselect the whole tier with -m "not e2e" (CI's per-PR job uses exactly this) when you
have no engine; use -m e2e to run only the e2e tests.
Project layout
src/gda/
cli.py # CLI entrypoint (Typer); command groups, --json/--schema, binary override
binary.py # Godot binary resolution (flag > $GDA_GODOT > default)
runner.py # GodotRunner seam (Protocol) + SubprocessGodotRunner (one-shot headless)
parser.py # sentinel-contract result parser (ADR-0002)
models.py # typed I/O models (Pydantic) backing --json and --schema (ADR-0004)
errors.py # failure classification: shared classify_run + per-command layers
exit_codes.py # the single registry of process exit codes (the CLI ABI)
ops/operations.gd # GDScript payload, dispatched by operation name
tests/ # unit tests + e2e tests against a real engine (shared fixtures in conftest.py)
docs/adr/ # architecture decision records
CONTEXT.md # the project's shared domain language
The only external boundary — spawning a Godot process — sits behind the GodotRunner Protocol
(runner.py). Fast unit and CLI tests inject a canned result through that boundary; the e2e suite
drives a real engine. Everything between the CLI and the runner runs as real code in both tiers.
Roadmap
| Phase | Delivers |
|---|---|
| Phase 1 | gda serving headless operations standalone: info, structured errors, --schema, and domain command groups (scene, node, script, project, resource, export, …). |
gda-mcp | A thin MCP adapter generated mechanically from --schema — first on top of Phase 1, following gda forward automatically. |
| Phase 2 | gda also serving live operations through gda-daemon's persistent engine connection. |
Track progress and proposals on the issue tracker.
Contributing
Contributions are welcome. Before starting:
- Read
CONTEXT.mdto align with the project's shared language, and review the relevant ADRs for the area you're touching. - Issues and PRDs live as GitHub issues in
aigengame/godot-agent.
Commits follow the Conventional Commits specification.
Working with an AI coding agent? This project is built to be agent-navigable.
AGENTS.mdis the entry point for coding agents — it wires in the project's rules, domain docs, and skills.
Acknowledgements
gda's design draws on two reference implementations from the Godot + agent ecosystem: the
one-shot-headless approach of godot-mcp and the persistent editor-plugin approach of
godot-mcp-pro. gda deliberately adopts a hybrid, phased strategy that combines their
strengths (see ADR-0001).
License
Released under the MIT License. Copyright (c) 2026 aigengame.