AnkusDrive

AnkusDrive

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.

# 1. Install FreeCAD 1.1.x from https://www.freecad.org/

(macOS: drag to /Applications; Linux: distro package or AppImage;

Windows: run the installer — default C:\Program Files\FreeCAD 1.1)

2. Install AnkusDrive. Pick one:

pipx install ankusdrive # from PyPI — isolated app, ankusdrive on PATH pip install ankusdrive # or into an env you manage yourself

unreleased main, or for development from a clone:

pipx install git+https://github.com/gchen19/AnkusDrive.git git clone https://github.com/gchen19/AnkusDrive.git && cd AnkusDrive python3 -m venv .venv && .venv/bin/pip install -e . # .venv/bin/ankusdrive

3. Smoke-test that the worker can reach FreeCAD, and see the full setup report

ankusdrive ping # → ping=pong freecad=1.1.1 ankusdrive doctor # per-item FreeCAD + solver checklist with the exact fix each

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.

# 1. A container engine: Docker Desktop, OrbStack, colima or podman.

2. Pull the solver image (0.88 GB on Apple Silicon, 1.15 GB on Intel).

docker pull ghcr.io/gchen19/ankusdrive-solvers:latest

3. Check it is ours before running your geometry through it (see below).

bash scripts/verify-container-image.sh

4. Point AnkusDrive at the container substrate.

export ANKUSDRIVE_SUBSTRATE=container

optional: ANKUSDRIVE_CONTAINER_ENGINE=podman|nerdctl (default docker)

optional: ANKUSDRIVE_CONTAINER= (default ankusdrive-solvers)

5. Create the container. $TMPDIR must be mounted at the SAME path inside, because a

case directory has to mean the same thing on both sides. On macOS $TMPDIR is a

per-user /var/folders/... path — mount THAT, not /tmp.

docker run -d --name ankusdrive-solvers \ --user "$(id -u):$(id -g)" -e HOME=/tmp \ --network none --cap-drop ALL --security-opt no-new-privileges \ --read-only --tmpfs /tmp:rw,exec,size=2g \ -v "$TMPDIR:$TMPDIR" \ ghcr.io/gchen19/ankusdrive-solvers sleep infinity

6. Export the in-container paths for the OpenFOAM-backed families. The image

publishes them; YADE, Elmer, openEMS and Bempp need no export — AnkusDrive finds

them by asking the container.

docker exec ankusdrive-solvers env | grep -E \ '^ANKUSDRIVE_(OPENFOAM_PATH|OPENFOAM_BASHRC|FSI_OPENFOAM_BASHRC|CCX_PRECICE|PRECICE_LIB|OPENFOAM_ADAPTER_LIB|OPENINJMOLDSIM|OPENINJMOLDSIM_BASHRC)='

7. Confirm.

ankusdrive doctor # each family: ready via (in container) ankusdrive doctor --verify-image # …and that the image is signed by this repo

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

Both are public, multi-arch (linux/amd64 + linux/arm64, each built natively) and tagged latest plus sha- .

Every published manifest is signed through Sigstore with a short-lived GitHub OIDC identity — no key to store or leak — and carries provenance naming the repository, workflow and commit that built it, plus a CycloneDX SBOM of what is inside:

bash scripts/verify-container-image.sh                       # the slim image, :latest

bash scripts/verify-container-image.sh ghcr.io/gchen19/ankusdrive-solvers@sha256:

Needs the GitHub CLI (gh ≥ 2.49, authenticated). Verify a digest and then run that digest: verifying :latest today and pulling :latest next week are two different images. ankusdrive doctor prints the digest the running container was made from, and --verify-image checks it.

There are three answers, and only one is alarming: verified; unsigned (an image you built yourself, or one published before signing existed — silence it with ANKUSDRIVE_ALLOW_UNVERIFIED_IMAGE=1); and mismatch, an image carrying provenance from somewhere else, which no setting silences. Verification never blocks a solve.

Building your own — a subset, or with your own changes — takes minutes, because nothing is compiled (the prebuilt solver trees are copied):

tools/build_solver_image.sh --solvers "openfoam fsi" -t my-solvers:dev   # 0.69 GB

Windows quickstart (PowerShell)

Windows is a first-class target (core CAD + CalculiX FEM run natively against a stock FreeCAD 1.1 install), and the whole core install is one script — venv, pinned dependencies, doctor, and the MCP registration line with resolved absolute paths:

# 1. Install FreeCAD 1.1.x from https://www.freecad.org/ (default C:\Program Files\FreeCAD 1.1).

Nothing needs to go on PATH — AnkusDrive globs the versioned install dir itself.

2. Clone and run the core installer. Windows PowerShell 5.1 is enough; no admin needed.

git clone https://github.com/gchen19/AnkusDrive.git cd AnkusDrive powershell -ExecutionPolicy Bypass -File scripts\install-core.ps1

That creates .venv, installs AnkusDrive with the pins that matter (notably mcp<2 — mcp 2.x installs cleanly and then breaks ankusdrive mcp), verifies the resolved mcp/numpy/Pillow, runs ankusdrive doctor + ankusdrive ping, completes a real MCP stdio handshake, and finally prints your registration block. Useful switches: -Python 'C:\Program Files\Python313\python.exe' to pick an interpreter, -Extras mbd,fluids for the pip-wheel solver families, -Persist to write the FreeCAD path into %APPDATA%\ankusdrive\config.toml (MCP hosts launch with a minimal environment, so a $env: set in your terminal will not reach them).

3. Register it with your MCP host. The script prints these with your real paths filled in — a GUI host doesn't inherit your shell PATH, so the absolute path matters:

# Claude Code

claude mcp add ankusdrive -- C:\Users\you\AnkusDrive\.venv\Scripts\ankusdrive.exe mcp

Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json