apolo-cad

English · Español

What it is

Apolo is a headless parametric CAD (OpenCascade through build123d) with a FastAPI server and a three.js web viewer. Every operation is a command against one HTTP API, and the AI agent, the web UI and the MCP server are equal clients of that API.

The goal is not button parity with SolidWorks or Inventor. Those tools are built around a person clicking; Apolo is built around an agent that has to reach the same result a competent engineering office delivers:

• a 3D model that can be fabricated and holds itself up (fastening, load path, clearances, gravity checked, not assumed);

• shop drawings, a calculation report that cites its standards, a costed BOM and quotation, and a step-by-step assembly manual;

• since V8, the machine's control panel, PLC program and pneumatics, tested in a virtual commissioning run before anything is built.

The agent works with engineering judgment by default: what is removable gets bolted, guards are supported and fastened, and a design is not called done while something floats, collides or lacks declared fastening.

Related MCP server: gitcad

See it

The control panel, in 3D

The agent declares the circuit (devices with terminals, wires, conductors) and layout_tablero builds the panel: enclosure, DIN rails, wire ducts, devices, and the door with its operators. Apolo runs an electrical rule check (short circuits, crossed voltages, unprotected motors, earthing), adds the panel to the BOM and costing, and the PLC program runs against the real terminals.

What you get from one model

Quick start

pip install "apolo-cad[physics,fea]"   # extras: MuJoCo physics, linear static FEA
apolo --open                            # API + web UI on http://127.0.0.1:8000

Python 3.11–3.13; CI runs on Linux and Windows. Your projects are stored in ~/.apolo/ (APOLO_HOME changes it). apolo-cad[sketch] forces the PlaneGCS sketch solver where no wheel is published; otherwise the sketcher falls back to SciPy.

Connect an agent over MCP

Keep apolo running and register the stdio server in any MCP client (Claude Code, Claude Desktop, …):

{
  "mcpServers": {
    "apolo-cad": {
      "command": "apolo-mcp",
      "env": { "APOLO_URL": "http://127.0.0.1:8000" }
    }
  }
}

The server is also listed in the official MCP registry as io.github.mariorojasmz/apolo-cad. Then ask in plain language:

"Design a 4 m × 600 mm belt conveyor for 1–15 kg parcels, with a hollow-shaft gearmotor and a control panel with an emergency stop. Check that nothing collides or falls, and give me the drawing set and the calculation report."

The agent works in a loop: it models with run_batch (atomic batches: one regeneration, one undo step, with an optional contract that rolls the whole batch back if a clearance or interference assertion fails), looks with render_view and measure, validates with check_interference, gravity_test, engineering_check and delivery_check, and documents with drawing_set, calc_report, quotation and assembly_manual.

The write core is small (run_command, run_batch, edit_command, edit_batch, undo/redo) and covers the whole command registry; the rest of the 92 tools read, measure, simulate and produce documents. Everything the agent does is a command in the log: editable, undoable and visible live in the browser.

How it works

   AI agent (MCP) ──┐        ┌── web UI (React + three.js)      equal clients
                    ▼        ▼                                  of one HTTP API
               core/apolo/api      FastAPI · REST + WebSocket · jobs
                    │
   doc        document = command log (event-sourced, undo/redo, KB-sized .apolo files)
   commands   command registry + JSON Schemas: UI, dialogs and agent tools from one source
   kernel     build123d / OpenCascade: B-rep, rendering, measurement, picking
   library    standards-based catalog, BOM, costing, engineering rules
   assembly   joints, mates, constraints, connectivity
   drawing    HLR drawings, drawing sets, calculation report, manual
   physics    MuJoCo: gravity, drop test, dynamics          fea   gmsh + scikit-fem
   plc        Structured Text compiled to safe Python       cosim electrical + PLC + mechanics

• The document is a command log. Geometry is never stored: opening a file replays its log, so files are KB-sized and every past command stays editable.

• Schema-driven. A command added to the registry appears in the toolbar, the dialogs, the properties panel and the agent's tools without further code.

• Expressions everywhere. Any numeric field accepts "=expression" over project variables; changing a variable regenerates the model.

• Declarative selectors for edges and faces (direction, face, length, proximity) instead of fragile topological names.

• Machine templates are super-commands (create_belt_conveyor, create_roller_conveyor, create_hoist_chain, create_pneumatic_cylinder, layout_tablero, …): they inherit parametric editing, undo, BOM and agent exposure.

• A 469-reference catalog built from standard dimensions (ISO, DIN, EN, ASTM): bearings, profiles, fasteners, gearmotors, electrical and pneumatic devices.

The living machine (V8)

The current roadmap gives each machine its real control system:

• Electrical model: devices with terminals, wires and conductors; ERC; electrical BOM and costing.

• 3D control panel: rails, ducts, devices and door, wire lengths, duct fill, heat dissipation (IEC 60890) and cable glands.

• PLC: the program is written in Structured Text (IEC 61131-3) and compiled to a safe, deterministic scan with a watchdog.

• Co-simulation: the supply feeds the panel, the PLC reads sensors and drives contactors and drives, the motors move the MuJoCo physics, and each test scenario comes out green or red. In the viewer you press the panel's buttons and watch the machine respond.

• Pneumatics: FRL, valves, cylinders and hoses; the cylinder pushes with its force, speed set by flow and its air consumption; ISO 1219 schematic.

Status

V1–V7 are closed: modeling, assemblies, drawings, deliverables, robustness and performance. V8, the living machine, is in progress: the electrical model, physics, co-simulation and the live viewer are done; the 3D panel, pneumatics and the hoisting chain are being completed. Details in the roadmap.

Maturity is measured by deliverables, not features: the same machine's package from Apolo is scored against a package finished by hand, with a public rubric (benchmark).

Before a machine is delivered, a second agent reviews it blind, with a shop-floor checklist (reviewer prompt); every confirmed defect becomes a rule.

Out of scope on purpose: CAM, contact or non-linear FEA, multi-user cloud and generative design.

From source

python -m venv .venv
.venv\Scripts\python -m pip install -e "core[dev,physics,fea]"
cd ui ; npm ci ; npm run build ; cd ..
.\start-apolo.ps1                                   # API + UI on http://127.0.0.1:8000
.venv\Scripts\python -m pytest tests -q -n auto    # 6641 tests

The repo ships a .mcp.json for the source checkout. The web UI also has an optional built-in chat, off by default (APOLO_CHAT=1 and ANTHROPIC_API_KEY).

Contributing

Contributions are welcome. Read CONTRIBUTING.md first: what gets accepted, how to run the tests and the build, and the commit style. On your first pull request you'll be asked to sign the Contributor License Agreement once, through CLA Assistant. To report a security problem, follow SECURITY.md.

License

MIT © 2026 Mario Rojas.

Built on free software: OpenCascade (LGPL), build123d (Apache-2.0), FastAPI (MIT), three.js (MIT), MuJoCo (Apache-2.0), gmsh (GPL, optional fea extra) and scikit-fem (BSD).