structuresynth-mcp

MCP (Model Context Protocol) server for Structure Synth — generate 3D meshes from EisenScript grammars, headlessly.

Give an LLM agent a tool to write procedural 3D structure grammars and get back real geometry (Wavefront OBJ) with mesh statistics, ready for viewing, 3D printing, or further processing.

What it does

Rendering is powered by libssynth (ssynthgen), a modernized, Qt-light port of Structure Synth's engine that exports OBJ from the command line. This MCP server is a thin Python wrapper.

Patched engine: the recommended ssynthgen build includes small patches (upstream-able) that give parse errors real line numbers, exit code 1 instead of SIGABRT, and color-group OBJ output (usemtl #rrggbb groups, converted to .mtl by this server). Build instructions below.

Related MCP server: nexus3d

Requirements

1. Python ≥ 3.10 and uv (or pip).

2. ssynthgen — build once from libssynth:

   git clone https://github.com/jcelerier/libssynth.git
   cmake -S libssynth -B libssynth/build -DCMAKE_BUILD_TYPE=Release
   cmake --build libssynth/build -j
   # put it somewhere on your PATH, e.g.:
   cp libssynth/build/ssynthgen ~/.local/bin/

   Dependencies: CMake ≥ 3.13, a C++20 compiler, Qt5 (Core/Gui/Xml), Boost headers, fmt.

   If ssynthgen is not on PATH, point the server at it:

   export SSYNTHGEN_PATH=/path/to/ssynthgen

Install

git clone https://github.com/Astrid3333/structuresynth-mcp.git
cd structuresynth-mcp
uv sync                    # core
uv sync --extra export     # + matplotlib/trimesh for preview, STL/glTF export

Run

uv run structuresynth-mcp          # stdio MCP server

Use with an MCP client

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "structuresynth": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/structuresynth-mcp", "run", "structuresynth-mcp"],
      "env": {
        "SSYNTHGEN_PATH": "/home/you/.local/bin/ssynthgen"
      }
    }
  }
}

opencode

opencode mcp add structuresynth -- uv --directory /absolute/path/to/structuresynth-mcp run structuresynth-mcp

EisenScript in 30 seconds

set maxdepth 40
set seed 42

r1

rule r1 maxdepth 10 {
  { x 1 ry 10 } r1
  { y 1 hue 20 } r1
  box
}

Rules call each other; transformations in { } modify the state; primitives (box, sphere, cylinder, tube, grid, line, point, circle, cone, torus, helix, …) draw geometry. See the official EisenScript reference and the bundled examples.

Limits

• The bundled engine (libssynth) covers the core language; a few exotic original examples (e.g. Konstrukt.es, Thingy.es) use primitives or features it does not implement (torus, cone, helix, circle, point, tube).

• Parse errors report (line N) when using the patched ssynthgen build; the stock upstream build aborts with a generic message.

• preview_* uses matplotlib's software renderer — fine for previews, not ray-traced quality; previews are skipped for meshes above 50k faces.

• JavaScript animation scripting of the original GUI app is out of scope.

License

MIT for this MCP server. libssynth and Structure Synth are LGPL; bundled .es example scripts are from the official Structure Synth distribution — see src/structuresynth_mcp/examples/ATTRIBUTION.md.

Credits

• Structure Synth by Mikael Hvidtfeldt Christensen (Syntopia).

• libssynth by Jérémie / contributors — headless engine.

• Model Context Protocol.