Procedura

Procedura turns text or a reference image into a 3D model you can edit. It builds one part at a time, checks and improves the shape, adds materials, and exports files for moving parts.

Run it inside Codex or Claude Code through MCP. It uses the model in your current session. You do not need a separate model API key. Your agent's usual usage limits and billing apply.

News

• 2026-10-20 — MCP release. Run Procedura inside Codex or Claude Code with the model in your current session. See the setup guide.

Quick start

You need Git, curl, Python 3.11+ with venv support, and Codex or Claude Code. Sign in to your agent before you start.

The setup script supports Linux x86_64. It installs Bun, OpenSCAD, Blender, and the Python packages. See the MCP guide for other platforms and setup options.

1. Install

curl -fsSL https://raw.githubusercontent.com/SpatiaOS/Procedura/main/scripts/install-mcp.sh \
  | bash -s -- --agent both

This installs into ~/.local/share/Procedura and sets up both agents. Use --agent codex or --agent claude to set up just one.

For an existing clone, run this from its folder:

bash scripts/install-mcp.sh --agent both

2. Open your agent

cd ~/.local/share/Procedura
codex

Run claude instead of codex for Claude Code. If you used a clone, open the agent from that folder instead.

Choose your model and reasoning effort in the agent. Follow its project and MCP trust prompts. Restart the agent if it was open during setup.

3. Ask for a model

Describe what you want and give the path to a PNG image:

Use Procedura to build the rover in /absolute/path/rover.png. Run the full pipeline. Show me the preview, output files, and any warnings or failed checks.

You can also use $procedura in Codex or /procedura in Claude Code. Keep the session open until the run ends. Large models can take hours.

For a model without an image, ask for a text-only run. You can also ask the agent to make a reference image if it has a built-in image tool.

Output files

Find your files in outputs/mcp/<run_name>/ inside the project folder.

File	What it contains
final.scad	Source code you can edit in OpenSCAD
final.obj	The 3D mesh
final_painted.*	The model with materials
preview_final/, preview_painted/	Preview images
motion/	USD and URDF files for moving parts, plus motion test results
.cx/completion.json	Run result, warnings, and a list of output files

The final report lists any failed or skipped steps. Check the previews and the report to see what the run produced.

Good to know

• Physics checks need Isaac Sim. Install it separately. If it is missing, the report says that these checks did not run.
• Use one case per project folder. To run cases at once, use a separate clone and agent session for each case.
• Keep files and settings unchanged during a run. See the recovery guide if a run stops.

Guides

• MCP guide: setup, text-only models, and help with failed runs.
• API guide: use a model API key, run batches, or repeat a stage.
• Studio: run the web app. It uses the API setup.

Credits

The code that connects to models uses design ideas from opencode and openclaw. Both projects use the MIT license.

License

MIT. See LICENSE. OpenSCAD and Blender are separate tools with GPL licenses.