Godot Agent

godot-agent (gda): Godot AI Agent CLI, Skill, and MCP Server

Read this in: [简体中文](docs/README.zh-CN.md) · [Español](docs/README.es.md) · [日本語](docs/README.ja.md)

> gda gives your AI coding agent — or your shell scripts and CI — structured, machine-readable > control of the Godot Engine. Create scenes, edit nodes & scripts, > and export builds headlessly, then drive a running game live: runtime tree, input, > screenshots, performance — one command surface, three ways in.

[](https://pypi.org/project/gda/) [](https://github.com/aigengame/godot-agent/actions/workflows/ci.yml?query=branch%3Amain+event%3Apush) [](https://www.python.org/) -478CBF) [](#how-it-works) [](https://modelcontextprotocol.io) [](LICENSE)

AI agents are great at writing GDScript and terrible at seeing what happened. gda closes that loop: your agent issues one operation and gets back a single clean JSON result it can act on — never engine logs it has to scrape. It runs in two modes:

• Headless — one-shot and stateless, zero setup. No editor plugin, no daemon,

nothing to install in your project. Create and edit scenes, nodes, scripts, resources, shaders and themes; analyze the project; export builds.

• Live — drive a running game through a background daemon for everything only a

live engine can do: read the runtime scene tree, get/set runtime properties, simulate input, capture screenshots, and sample performance.

> gda is pre-1.0: every command works end-to-end today, but the CLI surface may > still change before 1.0.

---

Contents

• [Why gda?](#why-gda)
• [Capabilities at a glance](#capabilities-at-a-glance)
• [Installation](#installation)
• [Quick start](#quick-start)
• [Choose your integration](#choose-your-integration)
• [How it works](#how-it-works)
• [Command reference](#command-reference)
• [Configuration](#configuration)
• [Contributing](#contributing)
• [License](#license)

---

Why gda?

• 🤖 Structured output, built for agents. Every command emits exactly one JSON

object on stdout (--json); engine banners, warnings and print() go to stderr. Your agent parses one result, not a wall of logs.

• 📐 Typed & self-describing. Every command's input and output are typed models that

also back a machine-readable --schema (a JSON-Schema contract), so an agent can discover and validate the whole surface programmatically instead of guessing.

• 🔀 CLI, Skill, and MCP — your agent's choice. Drive Godot from a terminal or CI with the

raw gda CLI, hand your agent a bundled Skill (gda skill) that teaches it how and when to use the CLI, or expose the same operations as MCP tools (gda-mcp, generated from the CLI's own schemas). One command surface, three ways in — pick whatever your agent supports.

• 🧩 Godot-native commands. Grouped by Godot object (gda scene create,

gda node add, gda game set) with a tiny, consistent verb vocabulary — zero learning curve if you already know Godot.

• ⚡ Headless by default, live when you need it. Headless operations need no daemon

and no editor — just a Godot binary. Live operations add real-time control of a running game over a Unix-domain-socket daemon, addressed by the same CLI grammar.

• 🛡️ Fails loudly, never silently. A missing or hung engine is bounded by a timeout

and mapped to a stable non-zero exit code plus a structured {"error": {…}} envelope — so a shell or agent can branch on the failure category without parsing prose.

---

Capabilities at a glance

| What you need | Reach for | | --- | --- | | Build project files from an agent or script | scene / node / script / resource / shader / theme — create & edit headlessly | | Parse results instead of scraping engine logs | --json (one clean object) and --schema (a JSON-Schema contract) | | Hand an agent Godot tools | the bundled Skill (gda skill) or the gda-mcp server | | Automate CI, exports, and project analysis | headless commands — no editor, no plugin, just a Godot binary | | Debug a running game's runtime behavior | gda daemon start, then game / diag / logger / perf / input / screen |

---

Installation

Requirements: Python 3.13+, and a Godot binary — 4.4+ for headless commands, 4.6+ on macOS/Linux for live (daemon) commands.

Install the CLI from PyPI onto your PATH:

uv tool install gda      # or: pipx install gda
gda --help

Other ways to install (pip, from source)

Into an existing environment:

pip install gda

From source (for development or unreleased changes):

git clone https://github.com/aigengame/godot-agent.git
cd godot-agent
uv sync                  # create the environment + install dependencies
uv run gda --help

---

Quick start

Point gda at your Godot binary, then ask the engine its version — no project needed:

export GDA_GODOT="/path/to/Godot"   # or pass --godot to any command
gda info --json
# {"major":4,"minor":6,"patch":3,"status":"stable","string":"4.6.3-stable (official)",…}

stdout is always clean JSON you can pipe; all engine and script diagnostics go to stderr:

gda info --json | jq .major   # → 4

Build a scene headlessly. Point gda at a Godot project (a directory with project.godot) once; relative paths then resolve inside it, and nodes are addressed by their path relative to the scene root:

export GDA_PROJECT="/path/to/your/godot-project"   # or pass --project to any command
gda scene create scenes/main.tscn --root-type Node2D --json
gda node add  scenes/main.tscn --type Sprite2D --name Hero --json
gda node set  scenes/main.tscn --node Hero --property position --value 10,20 --json
gda scene get scenes/main.tscn --json
# {"path":"scenes/main.tscn","root":{"name":"main","type":"Node2D","children":[{"name":"Hero",…}]}}

> No project? gda still runs projectless on plain filesystem paths (relative to your current > directory) — only res:// resolution needs a project. See [Configuration](#configuration).

**Drive a running game live. Live ops run the project's main scene**, so point it at the one you just built via Godot's application/run/main_scene project setting (the editor's Application → Run → Main Scene), then start the daemon (macOS/Linux, Godot 4.6+):

gda project set application/run/main_scene --value res://scenes/main.tscn --json  # a Godot project setting key
gda daemon start             # start the daemon for $GDA_PROJECT (installs the in-game harness)
gda game tree --json         # the runtime scene tree, after _ready
gda perf monitors --json     # live engine counters: fps, memory, node count
gda daemon stop

(gda screen capture works live too, but needs a windowed session — start the daemon with gda daemon start --windowed.)

---

Choose your integration

gda exposes the same command surface three ways — pick whichever your agent (or you) supports:

| Entry point | Best for | How | | --- | --- | --- | | CLI (gda) | humans, shell scripts, CI, and agents that can run commands | gda --json | | Skill (gda skill) | coding agents that support Agent Skills and prefer a token-light CLI workflow | print/install SKILL.md (below) | | MCP (gda-mcp) | agents that call tools over the Model Context Protocol | run the stdio server (below) |

Use it as a Skill

gda ships an agent Skill — a SKILL.md that teaches an AI agent how and when to drive Godot from the CLI. It's the lightest way in (no server to register), bundled in the package and version-locked to your install. Print it, or install it into your agent's skills directory:

gda skill                                              # print SKILL.md (redirect it anywhere)
gda skill --install --provider claude --scope user     # resolve a known agent's skills dir
gda skill --install --dir ~/.claude/skills/gda         # …or give the directory yourself

--install --provider --scope resolves a known agent's skills directory (--scope defaults to user); --dir is the neutral fallback for any other agent — there's no built-in default. The [skill recipes](docs/gda-skill.md) list each agent's directory (Claude Code's ~/.claude/skills/, Codex's ~/.agents/skills/, …). Or fetch the same file straight from the repo, if you'd rather not go through gda skill — you still install gda, since the Skill drives it:

curl --create-dirs -o ~/.claude/skills/gda/SKILL.md \
  https://raw.githubusercontent.com/aigengame/godot-agent/main/src/gda/skill/SKILL.md

Use it as an MCP server

gda ships a stdio MCP server behind a [mcp] extra, so any MCP agent (Claude Code, Codex, Cursor, …) can drive Godot. Try it with no install:

uvx --from "gda[mcp]" gda-mcp

The server resolves two pieces of context — which Godot project to drive and which Godot binary to run (MCP can't pass per-call flags):

• Project — set GDA_PROJECT when your client can't advertise workspace roots; otherwise

gda-mcp auto-detects the project from the roots the client sends (the folder you have open). A set-but-invalid GDA_PROJECT is a reported error, not a silent fallback. See [Configuration](#configuration) for the full CLI-vs-MCP resolution order.

• Engine — set GDA_GODOT to your Godot binary, e.g. "GDA_GODOT": "/path/to/Godot".

Register with Coding Agents

Claude Code

Project scope, .mcp.json at the repo root (auto-detects the project via roots):

{
  "mcpServers": {
    "gda-mcp": {
      "command": "uvx",
      "args": ["--from", "gda[mcp]", "gda-mcp"]
    }
  }
}

User scope (every project) — the CLI, which writes ~/.claude.json:

claude mcp add --scope user gda-mcp -- uvx --from "gda[mcp]" gda-mcp

Codex

Project scope, .codex/config.toml at the repo root (the project must be trusted):

[mcp_servers.gda-mcp]
command = "uvx"
args = ["--from", "gda[mcp]", "gda-mcp"]

[mcp_servers.gda-mcp.env]
GDA_PROJECT = "/absolute/path/to/your/godot/project"

User scope (available everywhere, but pinned to one project) — the same table in ~/.codex/config.toml, or add it with the CLI. Codex has no workspace variable, so GDA_PROJECT is an absolute path; use project scope if you work across several projects:

codex mcp add gda-mcp --env GDA_PROJECT=/absolute/path/to/your/godot/project -- \
  uvx --from "gda[mcp]" gda-mcp

Cursor

Project scope, .cursor/mcp.json at the repo root (${workspaceFolder} tracks the open project):

{
  "mcpServers": {
    "gda-mcp": {
      "type": "stdio",
      "command": "/path/to/uvx",
      "args": ["--from", "gda[mcp]", "gda-mcp"],
      "env": {
        "GDA_PROJECT": "${workspaceFolder}"
      }
    }
  }
}

User scope (available everywhere, but pinned to one project) — the same config in ~/.cursor/mcp.json with GDA_PROJECT set to an absolute path (${workspaceFolder} only works in project scope; use project scope for several projects). Cursor has no mcp add command — register via the JSON above or the Settings → MCP UI.

> Cursor is GUI-launched with a minimal PATH, so a bare uvx may not resolve — hence the > absolute command above; fill it with the output of which uvx. Full recipes — PATH > injection, Claude Desktop, user vs project scope, per-agent project pinning — are in the > [registration recipes](docs/gda-mcp-registration.md).

---

How it works

gda is three components serving operations in two modes:

| Component | Role | | ---------------- | --------------------------------------------------------------------- | | gda | The agent-facing CLI — exposes Godot with structured --json output. | | gda-mcp | An MCP server exposing the same operations as tools, from --schema. | | gda-daemon | A per-project process supervising a running game for live operations. |

• Headless operations run one-shot — no daemon, nothing to install (create a scene, edit

a script, export, analyze).

• Live operations require a running game — gda-daemon launches it, injects an inert

in-game harness, and brokers requests over a Unix domain socket (runtime tree, input, screenshots, performance, diagnostics).

The in-game harness gda-daemon injects is dev-only: gda export run strips it from the artifact entirely, and built any other way (editor GUI, raw godot --export) it still self-disables in the exported game — so a shipped game never runs anything daemon-related (and via gda export run, doesn't even carry it).

Platform & version support:

| Mode | Godot | Platforms | | ---- | ----- | --------- | | Headless | 4.4+ | macOS · Linux · Windows¹ | | Live (via gda-daemon) | 4.6+ | macOS · Linux² |

¹ Headless is cross-platform by design (one-shot processes, no platform-specific dependency) — Windows keeps the full headless surface, though CI does not exercise it yet. ² Live operations use Unix domain sockets, so Windows is not supported yet.

---

Command reference

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:

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

Every command supports --json and --schema — except gda schema itself, which emits the aggregate manifest as JSON directly. Commands that read or mutate a res:// path resolve a [project context](#configuration). Run gda --help for full flags — gda --help is the authoritative list of what is installed.

New here? A good first path: gda info → gda scene create → gda node add → gda script validate → gda export run; then go live with gda daemon start → gda game tree.

Meta — about gda / the engine itself

| Command | What it does | | ------- | ------------ | | gda info | Report the Godot engine version info. | | gda schema | Emit the whole command surface as one machine-readable JSON manifest. | | gda skill | Emit or install the bundled Agent Skill (SKILL.md) that teaches an agent how to drive gda. |

Headless commands — Godot 4.4+, all platforms

scene — scene files (.tscn)

| Command | What it does | | ------- | ------------ | | scene create | Create a new .tscn with the given root node type. | | scene get | Read a scene and report its structured node tree. | | scene list | Enumerate the .tscn scenes in the resolved project. | | scene get-exports | List the @export properties a scene's nodes' scripts declare. | | scene delete | Delete a scene file and report what was removed. |

node — nodes within a scene file

| Command | What it does | | ------- | ------------ | | node add | Add a node under a parent, optionally at --index: a built-in type, a class_name script, or --instance to compose another scene as an instanced child. | | node get | Read a node's properties (by node path) as typed JSON. | | node list | List a scene's node tree with each node's path relative to the root. | | node set | Set a node property, coercing the value to its declared

…

Source & license

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

• Author: aigengame
• Source: aigengame/godot-agent
• License: MIT

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