modelgen

Generate 3D models by describing them. Tell your AI agent "make me a witch's lantern" and it builds one with modelgen's tools, looks at renders, fixes what's wrong and exports files your app can load: GLB (web, Android, game engines, desktop) and USDZ (iOS, macOS, AR Quick Look).

Models are plain YAML files you can read, version and edit by hand.

Try it in your browser → Build a model in a 3D editor or describe it to your own AI chat, see its YAML, and download it. Nothing to install, no account, no API key.

Install

brew install guilospanck/tap/modelgen                                              # macOS, Linux
curl -fsSL https://raw.githubusercontent.com/Guilospanck/modelgen/main/install.sh | sh   # any Unix
npm install -g @guilospanck/modelgen                                               # with Node 20+

With npm you can also add it to a project instead of installing it globally, or run it without installing:

npm install --save-dev @guilospanck/modelgen   # then: npx modelgen build
npx -y @guilospanck/modelgen --help            # one-off, nothing installed

Windows: use npm (above), or download modelgen-<version>-windows-x64.zip from the releases.

Related MCP server: chisel

Use it from your agent

modelgen is an MCP server. Run it from the folder where your models should live.

Claude Code:

claude mcp add modelgen -- modelgen mcp

Claude Desktop, Cursor and other MCP clients (mcpServers config):

{ "mcpServers": { "modelgen": { "command": "modelgen", "args": ["mcp", "--project", "/path/to/project"] } } }

Without installing it, through npx:

{ "mcpServers": { "modelgen": { "command": "npx", "args": ["-y", "@guilospanck/modelgen", "mcp", "--project", "/path/to/project"] } } }

Then ask for a model. The agent will create it, add parts, capture renders to check its work and export it.

What to ask

Describe what you want; the agent does the rest.

Make a model:

• "Use modelgen to make a low-poly witch's lantern: lathed glass body, iron cap and handle. Capture it, fix any issues, and export GLB and USDZ to assets/."

• "Create a wooden treasure chest with metal bands and a lock. Use the mottle texture for the wood. Show me the capture."

• "Make a coffee mug with a handle, about 10 cm tall, and export it as GLB."

• "Build a simple stylized tree: a tapered trunk (tube) and a blob canopy. Keep everything connected."

• "Make a keyboard keycap, 18 mm square, with the word Esc on top in white."

Iterate on it:

• "Show me the lantern from the front and from the top."

• "The handle is too thin: make it twice as thick, then capture again."

• "Make the body taller and give the paper material an orange emissive glow."

• "Undo the last change."

• "Duplicate the left chair leg to make the other three, mirrored."

• "Inspect the chest and tell me which parts are floating."

Export and projects:

• "Set up a modelgen project here that exports GLB to web/public/models and USDZ to ios/Models, then build everything."

• "Export just the handle part of the lantern as its own GLB."

• "List my models and rebuild them."

Learn what's possible:

• "Ask modelgen which shapes and materials it supports."

• "What texture patterns does modelgen have?"

Tips:

• Ask for captures. The agent sees the render plus a list of problems ("handle is floating, nearest part is cap, 0.04 away"); "capture it and fix everything it reports" gets noticeably better results.

• Give real sizes. Units are meters: "a 30 cm lantern" beats "a small lantern".

• Name the building blocks when you care: lathe for round things (vases, bottles, lamp bodies), extrude for flat profiles, tube for handles, pipes and limbs, blob for organic forms, text for letters and labels, groups for parts that move together.

• Models are files: models/<name>.model.yaml in the project. You can read or hand-edit them; the agent picks up your edits, and its own edits keep your comments and formatting.

• Current limits: no boolean cut-outs or bevels yet (hollows are made with profiles), no ready-made kits (creature, furniture...), and script parts only when the server runs with modelgen mcp --allow-scripts.

Use it yourself

modelgen init                     # modelgen.yaml + models/
modelgen new lantern
modelgen edit lantern ops.yaml    # or: --op '{"add": {"part": {...}}}'
modelgen capture lantern          # previews/lantern.png + problems
modelgen export lantern --out assets --format glb,usdz
modelgen build                    # every output in modelgen.yaml
modelgen describe shapes          # reference for shapes, materials, ops...

Every command takes --project <dir>. Most take --json for machine-readable output (schema always prints JSON; mcp ignores it). Exit codes: 0 ok, 1 the model has problems or the operation failed, 2 bad usage.

Try it in the browser

The playground runs modelgen in your browser. Everything but script parts works there.

• Build in 3D. Add any shape, including text, and move, rotate and scale it with gizmos (W / E / R, optional snapping). Drag the points of profiles, paths and blobs. Regroup parts in the scene list, edit shapes and materials in the sidebar, or type the YAML directly. Undo and redo cover all of it.

• Fix problems in place. Problems show on the parts they belong to, and the common ones have a Fix button: a floating part moves to touch the model, and a missing material gets defined.

• Ask in words. The Ask tab writes a prompt for the change you describe. Paste it into ChatGPT, Claude, Gemini or any chat you use, then paste the reply back. The playground applies it as modelgen edits, and writes a follow-up for the same chat if anything is left to fix. The page itself talks to no AI and needs no API key.

• Keep your models. Start from an example or a new, empty model (it gets a random name until you give it one). Changes save automatically, in this browser only, and examples stay untouched: your first change saves a copy.

• Take it with you. Download GLB and USDZ, or copy a link that carries the model.

Every change is a modelgen edit, so the YAML keeps its comments and the result is a normal model file you can use with the CLI.

It deploys from main (site/ + bun run build:web, which writes web-dist/).

Model files

modelgen: 1
name: lantern
materials:
  paper: {color: "#e8a13a", roughness: 0.8, texture: {pattern: stripes, color: "#c4761f"}}
  iron: {color: "#2a2a2a", metalness: 0.8}
parts:
  - name: body
    lathe: {profile: [[0, 0], [0.2, 0.1], [0.25, 0.4], [0.15, 0.7], [0, 0.72]]}
    material: paper
  - name: handle
    tube: {path: [[-0.08, 0.74, 0], [0, 0.9, 0], [0.08, 0.74, 0]], radius: 0.012}
    material: iron

• Units are meters, +y is up, +z is the front, rotations are radians.

• Shapes: box, sphere, cylinder, cone, capsule, torus, plane, extrude, lathe, tube, blob (smooth organic forms), text (extruded letters, e.g. text: {string: Esc, size: 0.004, depth: 0.0004}) and group.

• Texture patterns: fur, feathers, scales, spots, stripes, mottle, flame, runes.

• Parts must touch: floating parts are reported and block export.

• modelgen describe has the full reference; modelgen schema prints the JSON Schema (for editor autocomplete).

See examples/ for a lantern, a crate, a mug, a keycap with a text legend and a scripted pebble.

Projects

modelgen.yaml tells build where to write what:

models: models
outputs:
  - dir: ../web/public/models
    formats: [glb]
  - dir: ../ios/App/Models
    formats: [usdz]
    models: ["*", "!draft_*"]

Advanced: script parts

When a shape can't be described in YAML, a part can run a JavaScript builder: { name: stone, script: { module: scripts/pebble.js, params: { seed: 4 } } }. Scripts are trusted local code. Agents can only add or change them when the server runs with modelgen mcp --allow-scripts. See modelgen describe scripts.

License

MIT. The text shape's built-in font is IBM Plex Sans (SIL Open Font License 1.1, see LICENSE-fonts.txt).