freecad-mcp

Hand-coded Python MCP server exposing parametric FreeCAD operations as LLM tools — the same tool-use plumbing used to give LLMs access to document stores, applied to a grounded CAD environment.

Project status

Stage: server skeleton complete — tool implementations next.

• ✅ Repo hygiene: .gitignore, README

• ✅ pyproject.toml — pins the MCP SDK (mcp==1.29.0), console script freecad-mcp

• ✅ .omp/mcp.json placeholder (OMP harness config)

• ✅ Step 2 — FreeCAD headless spike: proven natively (macOS) and in a Docker container

• ✅ MCP server skeleton — official SDK, stdio transport (src/freecad_mcp/server.py, pushed to GitHub)

• 🔜 Six tools, OMP harness wiring, security hardening, verification

The server speaks the MCP protocol over stdio but exposes no tools yet (list_tools returns an empty list). This README documents the foundation, the environment decisions everything else builds on, and the roadmap to a usable tool set.

Related MCP server: FreeCAD Robust MCP Server

Architecture

• In-process headless FreeCAD: the server imports FreeCAD/Part and runs geometry operations in its own process — no GUI, no separate CAD instance, no RPC bridge.

• Container runtime: the server runs in a Docker image where FreeCAD is installed as a Python library alongside the interpreter. This is the only setup where import FreeCAD is guaranteed to work for any reviewer.

• Why not native macOS? FreeCAD.app ships its Python bindings sealed inside the app bundle, compiled against its own embedded Python. Importing them from an external venv is fragile and machine-specific (a fight with rpaths and versions that breaks on every FreeCAD update). The container is reproducible by construction — and it exercises Docker, which is a stated requirement for this role.

Prerequisites

• Docker Desktop (any platform) — server and FreeCAD live in the image.

• Python ≥ 3.10 locally (for server development and tests).

Quick start

# Build the dev image (Debian bookworm, FreeCAD 0.20.2, Python 3.11 venv, MCP SDK)
docker build -t freecad-mcp .

# Verify FreeCAD imports inside the container
docker run --rm freecad-mcp app_env/bin/python -c "import FreeCAD; print(FreeCAD.Version())"

# Headless pipeline smoke: document → box → recompute → export STEP
docker run --rm freecad-mcp app_env/bin/python -c "import FreeCAD, Part; doc=FreeCAD.newDocument('t'); Part.show(Part.makeBox(10,10,10),'Box'); doc.recompute(); Part.export([doc.Objects[0]], '/tmp/t.step'); print('ok')"

# Run the MCP server (stdio) from a local checkout
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
freecad-mcp            # or: python -m freecad_mcp.server

The dev image currently installs the MCP SDK but not the freecad-mcp package itself; installing it into the image is part of the harness-wiring roadmap item below.

Known quirks (hard-won)

• Debian's freecad-python3 installs its bindings to /usr/lib/freecad-python3/lib — a non-standard path that Python never searches by default. The image sets ENV PYTHONPATH=/usr/lib/freecad-python3/lib to wire it up.

• Debian's python3 strips ensurepip, so creating a venv requires the python3-venv package (python3 -m venv fails without it).

• The macOS FreeCAD installer ships no FreeCADCmd binary — headless use on macOS goes through the app's bundled Python (/Applications/FreeCAD.app/Contents/Resources/bin/python) with PYTHONPATH pointing at Contents/Resources/lib.

• Docker Desktop's daemon must be running before docker commands work (open -a Docker on macOS).

Roadmap

• .gitignore, README

• pyproject.toml — Python ≥ 3.10, MCP SDK pinned (mcp==1.29.0)

• .omp/mcp.json placeholder

• MCP server skeleton (official SDK, stdio first) — src/freecad_mcp/server.py

• Six tools: create_document, create_primitive, execute_python, export_model, list_objects, get_object

• OMP harness wiring + verification (/mcp list, /mcp test freecad)

• Security hardening (sandboxed execute_python, export path guards, doc limits)

• Verification: MCP Inspector, Claude Desktop, OMP harness; pytest; CI

License

MIT