gchen19/AnkusDrive

gives
GitHub a dark variant; PyPI strips and falls through to . -->
A CLI + MCP server that drives FreeCAD through its Python API so LLMs (and humans at a terminal) can design mechanical parts and run FEM simulations without clicking through the GUI.
Why
FreeCAD exposes almost everything it does through a Python API — create documents, build sketches, extrude solids, mesh them, run CalculiX/Elmer FEM solves, read back stress/displacement fields. But that API lives inside FreeCAD's embedded Python (freecadcmd), which is awkward to call from anywhere else. AnkusDrive wraps it behind two surfaces:
- **CLI** — one-shot commands (ankusdrive run script.py, ankusdrive box --w 10 --d 20 --h 5 -o part.FCStd) for scripts, CI, and quick iteration.
- **MCP server** — 280+ structured tools (new_document, add_primitive, boolean_op, pad, add_gear, fem_new_analysis, fem_run, fem_results) so an LLM agent can model, inspect, and simulate iteratively. Beyond core CAD/FEM this now spans a broad **simulation surface** (thermal, CFD/CHT, EM, acoustics, FSI, injection molding, granular/DEM, optics, multibody) and a **design-control layer** (item/part numbers, recipes, variant families, lifecycle/revision, ECO change orders, versioned interfaces).
- **Multi-agent orchestration** — a host-side reference layer that lets a *team* of agents partition one product into components, build them in parallel, and merge the pieces back together with the joints actually fitting (see Multi-agent design).
Target environment
- FreeCAD 1.1.x. The freecadcmd binary is auto-discovered per-OS (macOS .app bundle, Linux /usr/bin etc., **Windows** C:\Program Files\FreeCAD 1.1\bin\freecadcmd.exe — version-globbed); override via $ANKUSDRIVE_FREECADCMD or rely on PATH. Run ankusdrive doctor to see exactly what resolved.
- Bundled Python, ccx (CalculiX), and gmsh already ship **inside every FreeCAD install** — the macOS .app, the Linux package, and the Windows bin\ — so core CAD + structural FEM work on all three with no extra install.
- Host-side rendering needs Pillow and numpy; both are installed by AnkusDrive as regular pip deps.
- **One optional exception:** drawing **PDF/SVG** export (export_drawing) renders inside FreeCAD's *bundled* Python, so it needs reportlab + svglib installed **there** — see Drawing export (PDF/SVG). DXF export and everything else leave FreeCAD's Python untouched.
Setup
AnkusDrive is a pip-installable package; FreeCAD itself is the only thing you
install separately. The host-side dependencies (mcp, Pillow, numpy) come
along with the install. freecadcmd is launched as a subprocess and uses its
own bundled Python — AnkusDrive doesn't touch it.
> **On Windows, don't follow the block above by hand** — there is one scripted path
> that does all of it including the MCP registration:
> Windows quickstart (PowerShell).
AnkusDrive is published on PyPI at
pypi.org/project/ankusdrive; the
distribution roadmap beyond it (marketplace listings, hosted transport) is
tracked in epic #303; the
original phase plan is kept as a design record at
docs/archive/PUBLISHING_PLAN.md.
macOS quickstart — solvers in a container
FreeCAD, CalculiX, SU2, PrusaSlicer and every pip-wheel family run **natively** on a
Mac; the block above is all you need for those. What has no practical macOS build is
the Linux solver stack — OpenFOAM, Elmer, YADE, openEMS, Bempp, preCICE,
openInjMoldSim. Those run in a container, and AnkusDrive stays on the host and reaches
into it. The image is multi-arch, so on Apple Silicon it runs **native, not emulated**.
The run flags are least privilege, and each is there because the solvers genuinely
do not need what it removes — verified by running the live solver suites with them on.
--network none in particular: nothing in a mesh is a reason to reach the internet.
**Don't copy the image's ANKUSDRIVE_FREECADCMD or ANKUSDRIVE_CALCULIX_PATH** — those
name paths inside the container, while FreeCAD and ccx run on your Mac.
A config.toml written for a native install is the one trap here: its absolute paths
are read as in-container paths. ankusdrive doctor now catches that and says so.
The alternative substrate on macOS is a Multipass VM, which you provision yourself —
docs/MACOS.md has the full per-solver reality on a Mac, and
docs/CONTAINER_SUBSTRATE.md the container path in depth.
The solver images, and checking they are ours
| image | what it is | size |
|---|---|---|
| ghcr.io/gchen19/ankusdrive-solvers | **what you want**: solvers and their runtime libraries, nothing else | 1.15 GB amd64 / 0.88 GB arm64 |