convez.ai
MCP ServerAutomaçãoAvançado
aigengame

Godot Agent

aigengame/godot-agent

CLI + MCP para IA controlar Godot com saída estruturada

Ver no GitHub
InicialPluginScore · de 0 a 100

Um 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-agent

1 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

Estrelas
58
Forks
10
Acompanhando
1
Saúde
50%
Último commit
há 2 semanas
Versão
v0.25.0
Issues abertas
79
Contribuidores
3

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)

godot-agent title image

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.

Status CI Python Godot Package manager License

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 --json and 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 --json today 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 --headless processes — 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

gda is in active early development (Phase 1). The architecture and contracts are settled (see CONTEXT.md and docs/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 info meta command and the first domain command groups — gda scene create / gda scene get / gda scene list / gda scene delete and gda node add / gda node list / gda node get / gda node set (ADR-0005).
  • ✅ The contract every shipped command carries: structured --json output, model-derived --schema self-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 --headless runner 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-daemon for 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:

ComponentRolePhase
gdaThe agent-facing Godot CLI — the bottom layer that exposes Godot with structured output1
gda-mcpA thin MCP adapter that exposes gda's capabilities as MCP tools, derived from --schema1+
gda-daemonA long-lived process holding a persistent connection to a running engine for live operations2
  • Headless operations need no pre-existing engine state and are fulfilled by a one-shot godot --headless process (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-daemon in 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+ — gda targets 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
VerbMeaning
create / deleteMake / remove a standalone entity (scene, script, resource)
add / removeAdd / remove a sub-entity within a container (node → scene)
get / listRead one entity / enumerate many
setMutate a property
domain verbsplay, run, export, import, … kept with their natural meaning

The surface grows one vertical slice at a time; gda --help lists 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

FlagDescription
--jsonEmit the result as a single JSON object on stdout. Without it, commands print a concise human-readable rendering.
--schemaEmit the command's input/output JSON Schema contract (no Godot spawned).
--godotPath to the Godot binary (overrides $GDA_GODOT and the default).
--projectGodot project directory for res:// resolution (overrides $GDA_PROJECT; defaults to the current directory if it is a project). Domain commands only.
--helpShow usage for gda or any command.

Configuration

gda resolves the Godot binary in this order (highest precedence first):

  1. The --godot <path> flag.
  2. The GDA_GODOT environment variable.
  3. A default development path — ~/Applications/Godot.app/Contents/MacOS/Godot (macOS). On other platforms, set GDA_GODOT or 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):

  1. The --project <dir> flag.
  2. The GDA_PROJECT environment variable.
  3. 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.

  • gda extracts 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

PhaseDelivers
Phase 1gda serving headless operations standalone: info, structured errors, --schema, and domain command groups (scene, node, script, project, resource, export, …).
gda-mcpA thin MCP adapter generated mechanically from --schema — first on top of Phase 1, following gda forward automatically.
Phase 2gda 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.md to 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.md is 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.

Ver o original no GitHub

Bom para

Relacionados