FreeCAD MCP

What FreeCAD MCP MCP server does

The FreeCAD MCP MCP server lets an AI agent work with documents inside FreeCAD rather than only generating detached scripts or descriptions. It is intended for interactive design work: the agent can help turn requirements into a parametric model, inspect an existing part, explain errors, and revise geometry with the user.

Supported workflows include Part and PartDesign modeling, sketch inspection, Draft work, Boolean and transform operations, measurements, mesh handling, geometry checks, and manufacturing preparation. The project also covers CNC toolpath generation and G-code export, although those capabilities depend on a newer FreeCAD build than the rest of the toolset. Examples in the documentation include importing an STL, adding mounting features, checking whether parts collide, and creating a reusable generator driven by spreadsheet dimensions.

How it works

FreeCAD must be running with the AICopilot workbench loaded. That workbench starts a local socket server, and the bridge discovers the available FreeCAD process so the agent can issue operations through MCP. The Report View provides visible startup and diagnostic information, including whether the workbench loaded and whether the socket is listening.

Multiple FreeCAD processes can be active at once. Each process creates a UUID, a socket path, and a discovery record under the user cache directory. The agent can list instances and select one by UUID or label. If no instance is selected, one live process is chosen automatically; with several live processes, explicit selection is required.

Setup and configuration

Installation follows the repository's AGENT-INSTALL.md instructions. The setup process includes installing prerequisites, cloning the repository, installing the FreeCAD addon, and registering the server with the agent. The documented development environments are macOS, Windows, and Linux, with other platforms less tested.

Optional launch variables can label an instance or replace its socket path:

• FREECAD_MCP_LABEL assigns a human-readable instance name.
• FREECAD_MCP_SOCKET overrides the generated socket location.

Agents can also start GUI or headless FreeCAD processes with spawn_freecad_instance, supplying a label and FreeCAD binary path. Verification consists of opening Report View and checking for the AICopilot startup and socket-server messages.

Tools and capabilities

The FreeCAD MCP MCP server provides more than 30 tools. Documented operations include:

• Listing and selecting running FreeCAD instances.
• Creating and editing parametric parts and sketches.
• Inspecting constraints, Report View output, and document state.
• Applying Boolean, transform, measurement, and geometry-check operations.
• Working with meshes such as imported STL files.
• Planning and generating CAM toolpaths where the installed FreeCAD version supports them.
• Exporting models as STEP and producing CNC G-code.
• Building reusable FreeCAD macros from design requirements.

The exact tool catalog is maintained in the repository's TOOLS.md reference.

Limitations and notes

CAM is not supported on FreeCAD 1.1.x in this project. It requires a current weekly development build because the Path workbench API changed between the stable and development series.

The bridge requires a live FreeCAD process with the AICopilot workbench available; it is not a standalone geometry engine. Platform testing is strongest on macOS, Windows, and Linux.