gdcli

CLI toolkit for Godot 4 — built for AI agents, works great for humans.

gdcli gives coding agents (and you) a structured, scriptable interface to Godot projects. It parses scenes, creates scripts, validates references, and lints GDScript — all from the command line, with machine-readable JSON output by default.

• Single binary — one Rust executable, no runtime dependencies
• Stock Godot 4 — works with any Godot 4 build, no patches needed
• Filesystem-native — scene/node/script operations parse .tscn files directly (instant, no Godot subprocess)
• MCP server — exposes all commands as tools for Claude, Cursor, Cline, and other MCP clients
• JSON by default — auto-detects piped output and switches to structured JSON

Add to your AI agent

Claude Code (one command, no install needed):

# macOS / Linux
claude mcp add --transport stdio gdcli -- npx -y gdcli-godot mcp

# Windows
claude mcp add --transport stdio gdcli -- cmd /c npx -y gdcli-godot mcp

Cursor / VS Code / other MCP clients — add to your MCP config:

// macOS / Linux
{ "mcpServers": { "gdcli": { "command": "npx", "args": ["-y", "gdcli-godot", "mcp"] } } }

// Windows
{ "mcpServers": { "gdcli": { "command": "cmd", "args": ["/c", "npx", "-y", "gdcli-godot", "mcp"] } } }

Using native binary (faster startup, requires Install first):

claude mcp add --transport stdio gdcli -- gdcli mcp

Why gdcli over godot-mcp

Other Godot MCP tools launch the Godot engine for every operation — adding a node, changing a property, wiring a texture all wait for the engine to start up. gdcli reads and writes .tscn files directly, so those same operations take milliseconds instead of seconds.

Concrete advantages:

• Speed — adding a node, editing a property, or wiring a sub-resource takes milliseconds. Agents iterate faster when the edit-lint-run loop isn't bottlenecked by engine startup.
• No runtime dependencies — cargo install or download the binary. No npm install, no node_modules, no version conflicts.
• CLI + MCP in one binary — every MCP tool is also a CLI command. Agents can use MCP; humans can use the shell; CI can use either. Same tool, same output format.
• Non-blocking project execution — run_start spawns Godot in the background and returns immediately. The agent can continue editing files, then poll with run_read or stop with run_stop. godot-mcp's run blocks the entire server.
• Works without Godot installed — scene creation, node manipulation, sub-resources, connections, UID fixes, project info, docs lookup — none of these need Godot on the machine. Only lint, run, doctor, and docs build require the engine.

Install

Download binary (fastest startup):

Grab the latest release for your platform from the Releases page — Windows, Linux, and macOS (universal) binaries available. Extract and add to your PATH.

From source:

cargo install --git https://github.com/mystico53/gdcli

Prerequisites

Godot 4 is required for commands that invoke the engine (doctor, script lint, run, docs --build). All other commands work without Godot installed.

If Godot isn't on your PATH, set GODOT_PATH:

export GODOT_PATH=/path/to/godot

On Windows, point to the .console.exe variant for proper stdout capture:

$env:GODOT_PATH = "C:\path\to\Godot_v4.x-stable_win64_console.exe"

Run gdcli doctor to verify your setup.

Commands

Diagnostics

Scripts

Scenes

Nodes

Sub-resources

Sprites

Connections

Project

UIDs

Docs

Runtime

Streaming sessions (MCP): For non-blocking execution, use run_start / run_read / run_stop via MCP. The agent starts Godot in the background, continues editing files, then polls for output — no server blocking.

MCP Server

JSON output

gdcli auto-detects when stdout is piped or redirected and switches to JSON. Agents get structured data by default — no flags needed.

Force JSON in a terminal:

gdcli doctor --json

Every response uses the same envelope:

{
  "ok": true,
  "command": "doctor",
  "data": { ... },
  "error": null
}

• ok — true if the command succeeded with no issues, false otherwise
• command — the subcommand name
• data — command-specific payload
• error — human-readable error string, or null

MCP server mode

gdcli includes a built-in MCP server that exposes all 24 commands as tools. Any MCP-compatible client (Claude Code, Claude Desktop, Cursor, Cline, etc.) can use it.

Configure in .mcp.json (or your client's MCP config):

{
  "mcpServers": {
    "gdcli": {
      "command": "gdcli",
      "args": ["mcp"],
      "cwd": "/path/to/your/godot/project"
    }
  }
}

The cwd should point to your Godot project root (the directory with project.godot). Alternatively, use the --project-dir flag:

{
  "mcpServers": {
    "gdcli": {
      "command": "gdcli",
      "args": ["mcp", "--project-dir", "/path/to/your/godot/project"]
    }
  }
}

All 23 tools are exposed: doctor, project_info, scene_list, scene_validate, scene_create, scene_edit, scene_inspect, node_add, node_remove, load_sprite, sub_resource_add, sub_resource_edit, connection_add, connection_remove, uid_fix, script_create, script_lint, run, run_start, run_read, run_stop, docs, docs_build.

Agentic workflow

  Agent                     gdcli                    Godot
    |                         |                        |
    |-- doctor -------------->|--- probe version ----->|
    |<-- JSON: ok, version ---|                        |
    |                         |                        |
    |-- script create ------->|                        |
    |<-- JSON: file created --|  (filesystem only)     |
    |                         |                        |
    |-- scene create -------->|                        |
    |<-- JSON: scene created -|  (filesystem only)     |
    |                         |                        |
    |-- load_sprite --------->|                        |
    |<-- JSON: sprite added --|  (filesystem only)     |
    |                         |                        |
    |-- node add ------------>|                        |
    |<-- JSON: node added ----|  (filesystem only)     |
    |                         |                        |
    |-- script lint --------->|--- --check-only ------>|
    |<-- JSON: errors[] ------|                        |
    |                         |                        |
    |   (fix errors in .gd)   |                        |
    |                         |                        |
    |-- run_start ----------->|--- headless run ------>|
    |<-- JSON: session_id ----|       (background)     |
    |                         |                        |
    |   (continue editing)    |          ...           |
    |                         |                        |
    |-- run_read ------------>|                        |
    |<-- JSON: new output ----|                        |
    |                         |                        |
    |-- run_stop ------------>|--- kill if running --->|
    |<-- JSON: all output ----|                        |

Architecture

gdcli commands split into two layers:

Contributing

gdcli is built with AI tools, for AI tools. Contributions using AI agents, copilots, or any other workflow are welcome — there's no disclosure requirement. What matters is the outcome.

Getting started

git clone https://github.com/mystico53/gdcli
cd gdcli
cargo build
cargo test

Quality gates

Every PR should pass these before review:

• cargo build compiles cleanly
• cargo test — all tests pass
• cargo clippy — no warnings
• Actually test the feature/fix with a real Godot project

Test suite

Unit tests live alongside the source. Integration tests live in tests/:

• tests/corpus_test.rs — round-trip idempotency test. Parses every .tscn file in a corpus of real Godot projects, writes it back, re-parses, writes again, and asserts the two outputs are identical. Run bash tests/fetch_corpus.sh to download the corpus (godot-demo-projects + tps-demo), then cargo test --test corpus_test. The corpus directory is gitignored and the test is skipped automatically if it's not present.

Areas of contribution

• New commands and features
• Better error messages
• Platform-specific fixes (Linux/macOS testing especially welcome)
• Documentation and examples

For AI agents

Start with AGENTS.md — it covers architecture, source layout, and design decisions. CLAUDE.md has project-specific instructions for Claude Code.

PR tips

• Keep PRs focused — one feature or fix per PR
• Describe what changed and why
• Mention what you tested (which Godot version, which OS, what scenario)

License

MIT