Model Context Protocol server for QuadSpinner Gaea 2 terrain automation.
Drive Gaea.Swarm.exe headlessly from any MCP client or AI agent: read
recipes, reshape them, run builds, verify results — and see the outputs.
Verified against Gaea 2.3.1.0, including real headless builds.
- Windows, Python 3.10+
- QuadSpinner Gaea 2 (any edition; mesh export needs a higher edition — the verifier tells you exactly that instead of failing mysteriously)
git clone https://github.com/harshit51290/gaea-mcp.git
cd gaea-mcp
python -m pip install -e ".[dev]"{
"mcpServers": {
"gaea": {
"command": "python",
"args": ["-m", "gaea_mcp.server"],
"env": { "GAEA_EXE": "C:\\Program Files\\QuadSpinner\\Gaea 2\\Gaea.Swarm.exe" }
}
}
}Engine lookup order: per-tool exe arg → GAEA_EXE env →
HKLM\SOFTWARE\QuadSpinner\Gaea\<ver> registry → default Program Files paths.
| Tool | Purpose |
|---|---|
locate_gaea_install |
Find engine, version, builds root (+ MCP server version) |
list_terrains |
Scan a dir for .terrain recipes with parsed summaries |
find_projects |
Find recipes by plain words, typo-tolerant, no path needed |
remember_project |
Name a recipe once, resolve it by name forever |
describe_terrain |
Recipe readout: resolution, nodes, exports, variables, profiles |
create_variation |
Clone a recipe + scalar node tweaks (topology never touched) |
add_plain_level |
Append Constant + Combine(Max): flat plains below peaks + export |
add_height_export |
Attach PNG16 height export to any node (enables measurement) |
rewire_port |
Point one input port at another node's output (e.g. File → Erosion) |
set_output_destination |
Set build Type/Destination (fixes silent no-output builds) |
preview_build_command |
Exact Swarm argv without executing (Copy Command Line) |
run_build |
Headless build → exit code + build-dir analysis |
batch_build |
Sequential multi-recipe builds |
list_builds |
Build output dirs (<project>/<NNN>), newest first |
get_build_report |
report.json + report.txt + crash issues for one build |
verify_build |
pass/fail verdict with severity (benign / warning / error) |
list_outputs |
Files in an output directory |
inspect_heightfield |
File stats, image metadata, raw sample stats |
see_output |
SEE the render (image) + relief stats — agent eyes |
Resources: gaea://install, gaea://cli-reference, gaea://recipe-format,
gaea://formats, gaea://verification.
Prompts: plan_automation_recipe, bridge_workflow.
describe_terrain → preview_build_command → run_build → verify_build → see_output
The skills/gaea-terrain skill file teaches agents this loop, the
plain-language routing ("my island map" → find_projects), the art-director
iteration pattern, and the real-Earth DEM workflow. Copy it into your agent's
skills directory.
Gaea.Swarm --Filename "<recipe.terrain>" [--profile Name] [--region Name]
[--seed N] [--resolution R] [--buildpath DIR] [--node ID]
[--silent] [--ignorecache] [--verbose] [--safemode] [--interactive]
[--vars vars.json] [--va a,b,c] [-v name=value ...]
Two hard-won facts encoded in the runner: --silent is always passed (Swarm
waits for a keypress otherwise and crashes headless), and Swarm stdout cannot
be captured (console-handle crash on pipes and files) — so the server runs
it in a hidden console and verifies via exit code + build directory.
.terrainfiles are lenient JSON (BOM/trailing commas tolerated).- A node exports iff it has
SaveDefinition.Filename. - A null
BuildDefinition.Typemakes Swarm exit 0 having built nothing. - Gaea heightmaps are relative (peaks ~0.3 normalized is normal) — "big" comes from relief contrast + importer Z-scale, not raw numbers.
python -m pytest -q # 23 tests, no Gaea install neededSee CONTRIBUTING.md. MIT licensed — LICENSE. Gaea is a trademark of QuadSpinner; this project is unaffiliated.