AnkusDrive

<!-- mcp-name: io.github.gchen19/ankusdrive --> <!-- ↑ Ownership proof for the official MCP Registry (#201): the registry reads it from the README *as uploaded to PyPI*, so it must survive every release and match `name` in server.json. tests/test_mcp_registry.py holds both to that. --> <!-- Absolute raw.githubusercontent URLs, not repo-relative paths: this README is also the PyPI project page, which resolves relative links against pypi.org. PNG rather than the SVG because raw.githubusercontent serves SVG as text/plain, so browsers refuse to render it as an image. The <picture> gives GitHub a dark variant; PyPI strips <source> and falls through to <img>. --> <p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/gchen19/AnkusDrive/main/logo/wordmark/ankusdrive-wordmark-dark-1280.png"> <img src="https://raw.githubusercontent.com/gchen19/AnkusDrive/main/logo/wordmark/ankusdrive-wordmark-1280.png" alt="AnkusDrive — align generative intent with the CAD kernel" width="640"> </picture> </p>

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=<name>                  (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 <solver> (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

| 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 | | ghcr.io/gchen19/ankusdrive-heavy | the CI image — also carries FreeCAD, the driver venv and every build toolchain, because the whole test suite runs inside it | 5.3 GB / 4.5 GB |

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

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:<digest>

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