FreeCAD MCP Server

List all open FreeCAD documents with their names, labels, file paths, object counts, and modification status.

Get a structured representation of a document's feature tree.

Returns every object with its TypeId, label, properties, dependency links (InList/OutList), validity state, and touch state. This is the primary tool for understanding what a FreeCAD model contains.

Args: doc_name: Document name. Empty string uses the active document.

Get a full property dump and shape analysis for a single FreeCAD object.

Returns all properties (with types, groups, and documentation), dependency info, validity state, and basic shape metadata if the object has geometry.

Args: name: Object name (e.g., "Pad001", "Sketch002"). doc_name: Document name. Empty string uses the active document.

Detailed topological analysis of an object's shape.

Returns shape type, volume, area, center of mass, bounding box, topology counts (vertices/edges/faces/solids), face classifications (plane/cylinder/cone/sphere/toroid with parameters), and edge details.

Use this to understand the geometric result of a feature — especially useful for diagnosing why a boolean or pocket operation produced unexpected geometry.

Args: name: Object name that has a Shape (e.g., "Pad001", "Cut001"). doc_name: Document name. Empty string uses the active document.

Deep inspection of a sketch's constraint health.

Returns constraint count, geometry count, degrees of freedom, whether the sketch is fully constrained, and a detailed list of every constraint (type, value, referenced geometry indices, driving status, and whether it is redundant or conflicting).

Also returns geometry elements with type-specific details (line endpoints, circle centers/radii, arc parameters).

This is the primary diagnostic tool for sketch problems — over-constrained, under-constrained, or conflicting sketches.

Args: name: Sketch object name (e.g., "Sketch001"). doc_name: Document name. Empty string uses the active document.

Recompute a document and track what changed.

Snapshots every object's validity before recomputing, then diffs against the post-recompute state. Reports:

• new_errors: objects that were valid before but are now invalid

• resolved: objects that were invalid but are now valid

• persistent_errors: objects that remain invalid

• valid_count: number of objects that stayed valid

Use this instead of raw recompute to understand the impact of changes.

Args: doc_name: Document name. Empty string uses the active document.

Execute arbitrary Python code in FreeCAD's interpreter context.

The script has access to: FreeCAD, FreeCADGui, App, Gui, doc (active document). Stdout and stderr are captured and returned.

Use this as an escape hatch for operations not covered by the specific tools above. For example: creating objects, modifying properties, running macros, or accessing FreeCAD APIs not yet exposed as tools.

Args: script: Python code to execute.

Capture the current 3D viewport as a base64-encoded PNG image.

Returns the image as a base64 string along with dimensions. Useful for visual inspection of the model state.

Args: width: Image width in pixels. height: Image height in pixels.

Hot-reload all FreeCAD addon handler modules.

Call this after editing handler code (in freecad_addon/handlers/) to pick up changes without restarting FreeCAD. Reloads all handler modules and re-registers them with the RPC server.