dcc-mcp-freecad

Production FreeCAD adapter for typed, durable parametric modeling and CAD exchange through DCC-MCP.

Illustrative workflow based on the live OpenSCAD → FreeCAD → Blender/Godot acceptance run; generated source is retained in docs/images/dcc-mcp-freecad-showcase-source.png.

Capabilities

• Detect FreeCADCmd and report the actual FreeCAD/Python runtime.
• Create, inspect, recompute, validate, copy, and dependency-safely edit FCStd documents.
• Add and update boxes, cylinders, spheres, cones, and tori with typed dimensions and placements.
• Create parametric union, cut, and intersection features.
• Import or export STEP, IGES, BREP, STL, and OBJ geometry.
• Return object links, placements, shape/mesh topology counts, volume, area, bounding boxes, file size, and SHA-256 provenance.

No arbitrary Python, macros, module paths, or FreeCAD command-line flags are accepted. The adapter invokes only its packaged method-dispatch driver.

Requirements

• Python 3.7+
• dcc-mcp-core 0.20.36+
• A FreeCAD version covered by the compatibility matrix below, with a working FreeCADCmd/freecadcmd

FreeCAD compatibility matrix

Supported host versions are declared in compat_matrix.json — that file is the contract, this section only points at it:

Both supported lines are exercised end-to-end on real FreeCAD in CI. A version outside the matrix is not silently downgraded to "probably fine": dcc-mcp-freecad doctor --json fails with an error_code (freecad_host_version_unsupported, freecad_host_version_unverified, freecad_host_version_unlisted, or freecad_host_version_unparsable), the supported ranges, and the command that pins a supported one. The same matrix is re-checked inside FreeCAD before any geometry work, so a skipped preflight does not turn into a silent modelling bug.

Install

Install the published wheel, prove the standalone FreeCAD runtime, then start the service:

python -m pip install --upgrade dcc-mcp-freecad
dcc-mcp-freecad doctor --json
dcc-mcp-freecad verify --json
dcc-mcp-freecad

See install.md for Windows, macOS, and Linux discovery, stable doctor exits, configuration, wheel upgrades, uninstall, and troubleshooting. FreeCAD remains OS/package-manager owned; the adapter does not download or cache external binaries.

Configuration

The service is a standalone DCC-MCP instance with no GUI PID. Every operation launches a clean FreeCADCmd process in safe mode with a temporary user config.

Agent workflow

dcc-mcp-cli list
dcc-mcp-cli search --query "FreeCAD create boolean export STEP"
dcc-mcp-cli load-skill freecad-session --dcc-type freecad --instance-id <instance-short>
dcc-mcp-cli load-skill freecad-modeling --dcc-type freecad --instance-id <instance-short>

Typical sequence: create_document → add_primitive → transform_object → boolean_operation → validate_document → export_geometry.

Safety contract

• Requested documents and geometry stay under configured allowed roots.
• Existing outputs require explicit overwrite=true.
• FCStd mutations happen on sibling staging copies and replace the original only after a successful, non-empty save.
• Failed mutations leave the original document byte-for-byte unchanged.
• Object names, dimensional fields, placements, formats, tessellation, result size, process output, and deadlines are bounded.
• Cancellation and timeouts terminate the owned FreeCADCmd process.
• Cascade removal is explicit and reports every removed dependent.

FreeCAD Python API reference: https://www.freecad.org/api/