🌐 Language: English  |  简体中文

gaea-mcp — an MCP server that actually drives Gaea 2

A QuadSpinner Gaea 2 automation toolkit that works: an MCP server plus a drop-in Skill package. Not a .terrain-file generator toy — a complete path from real elevation data to successfully exported output.

Verified: every file format, node parameter set and build procedure used here was tested against Gaea 2.3.0.1 on Windows, producing real 4096² heightmap and colour-map exports.

Verified / not yet verified — please read

Known limitation. The automatic "open project" step sends foreground keystrokes (Ctrl+O) to Gaea. On Windows a background process is often refused input by the foreground-lock policy — SetForegroundWindow can report success while SendInput never reaches the target window. A minimise-then-restore fallback and an "already loaded" short-circuit are in place, but this was not reproducible on every host.

Workaround: open the project once by hand (File ▸ Open). The Build Settings panel and button invocations that gaea_build needs are unaffected. The proper fix is to move key sending into the C# helper, which shares the process that activates the window.

Why this exists

Publicly available tools of this kind tend to produce .terrain files Gaea cannot open, or can open but cannot build. One such project's own notes say:

"The CLI subprocess encounters handle is invalid errors that do not indicate actual file corruption."

That reads the inevitable Gaea.Swarm.exe crash as harmless. It is not, and it is exactly where people get stuck. What is actually happening:

This toolkit bakes all of that into its defaults and its guards.

Install

# Requires Python 3.10+ and the .NET 8 SDK (the latter builds the GUI helper)
pip install -e .

# Preflight: finds Gaea, can it build the helper, can it reach the GUI
gaea-doctor

gaea-doctor reports the install path, version, licence type, and the build / cache / log directories, and checks for the known traps. Run it before anything else.

Wiring into an AI client

{
  "mcpServers": {
    "gaea": {
      "command": "gaea-mcp"
    }
  }
}

Tools

Recommended order

gaea_doctor                      # confirm the environment
      ↓
gaea_fetch_copernicus_dem        # for a real place (optional)
  or gaea_make_fractal_heightmap
      ↓
gaea_prepare_heightmap           # normalise + build masks
      ↓
gaea_create_project              # author the .terrain
      ↓
gaea_validate_in_gaea            # ★ let Gaea itself judge
      ↓
gaea_build                       # trigger the build
      ↓
gaea_read_build_report           # confirm the outputs

Do not skip gaea_validate_in_gaea. An offline audit cannot see everything Gaea's loader objects to; skipping it is gambling with build time.

Hard constraints encoded in the code

Terrain.Height is the elevation SPAN, not a Y size

Terrain.Width  = ground span in metres
Terrain.Height = max_elevation - min_elevation    <- the relief
Compression    = Height / Width

Gaea defaults to Width=5000 / Height=2500 (ratio 0.5). Copying that onto real 400 m hills renders 2.5 km peaks — the single most common source of unrealistic terrain. West Lake's hills are truly 12000 m / 415 m = 0.0346.

Keep the normalisation consistent

0.0 ↔ lowest point       1.0 ↔ highest point
norm = (metres - min_m) / (max_m - min_m)

Bitmaps come from Export, not Mesher

{"$type": "QuadSpinner.Gaea.Nodes.Export, Gaea.Nodes",
 "Format": "PNG16", "Location": "Explicit",
 "OutputPath": "D:/out/terrain_heightmap"}

OutputPath must not include an extension — Gaea appends one per Format.

Erosion2 must carry Version: 2

{"Duration": 40.0, "Downcutting": 0.2, "Seed": 12345,
 "Enable": true, "Version": 2}

Without Version, Gaea attempts an old-schema migration, null-references, and every downstream consumer reports port In returned bad or no data.

RelativePath: true resolves against the project folder

{"FileName": "heightmap.png", "RelativePath": true}

The data file must sit beside the .terrain.

Erosion masks must be 16-bit greyscale

An 8-bit or palette PNG is mis-read as 16-bit:

WRN Array length doesn't conform Map resolution! Requested: 16777216, Received: 33554432

The mask is then applied only partially — the "protected" area still erodes, silently.

Flatten water in the data, then protect it with a mask

Erosion2 erodes everything it is allowed to reach. A lake or plain must be flattened before Gaea sees it, and then protected. Both together are what produce a mathematically exact water level (measured: mean 7.150 m, σ 0.0 mm).

How to build

Gaea.exe -Path <file>      ✗ crashes on this build
run Gaea.Swarm.exe direct  ✗ always IOException while the GUI holds the licence
Ctrl+Shift+B               ✓ build shortcut (Ctrl+B only opens the settings panel)
GUI: Ctrl+B → Execute Build → "Start Build" | "Close Gaea and Build"

Close Gaea and Build shuts the GUI down to free the licence and then builds — most reliable, and the only option when one seat is shared.

Node types that reject hand-written parameters

Thermal2 · SatMap · WaterColor · Lake · Sea · Rivers · Thermal

They are not unusable — their parameter sets are unknown. To use one, add it in the GUI, set its parameters, save, and read the exact JSON back.

Layout

gaea_mcp/
├─ pyproject.toml
├─ README.md / README.zh-CN.md   docs (EN / ZH)
├─ LICENSE / NOTICE.md           MIT + third-party notices
├─ selftest.py                   offline checks (no Gaea needed)
├─ acceptance.py                 end-to-end check (has Gaea load a generated project)
├─ skill/                        installable AI Skill package
│  └─ gaea-terrain/
│     ├─ SKILL.md
│     └─ reference/
│        ├─ FILE_FORMAT.md
│        ├─ NODES.md
│        ├─ BUILD.md
│        └─ TROUBLESHOOTING.md
└─ src/gaea_mcp/
   ├─ config.py                  locate install, version, licence, directories
   ├─ terrain.py                 .terrain schema + builder + structural audit
   ├─ outputs.py                 heightfield/mask IO, normalisation, hillshade, fractal DEM
   ├─ uia.py                     UI Automation bridge (compiles the C# helper)
   ├─ gaea.py                    launch / open / build / read-report orchestration
   ├─ server.py                  MCP tool definitions
   ├─ doctor.py                  command-line preflight
   └─ uia/uia.cs                 C# helper that drives Gaea by control name

Self-test

python selftest.py      # offline: file format, $id graph, mask bit depth, guards
python acceptance.py    # online: have Gaea load a generated project and report

Licence

MIT — see LICENSE. Third-party and trademark notices: NOTICE.md.

This is an independent, unofficial integration with no affiliation to QuadSpinner and contains none of their code or assets. You need your own valid Gaea 2 licence to use it.