FreeCAD MCP: an AI agent in parametric CAD
FreeCAD MCP (blwfish)
An MCP bridge between an agent and FreeCAD: 41 tools for parametric parts, CAM toolpaths, meshes and model diagnostics
- 66 ★ on the repository
- Last commit
- LGPL-2.1
Broad access
Why this level
- The arbitrary Python tool gives the agent filesystem and OS access through the FreeCAD environment
- Contents of open FreeCAD files reach the agent context: a file from an untrusted source can carry harmful instructions
Install
- Works in
Manual install
Go to https://github.com/blwfish/freecad-mcp and read the AGENT-INSTALL.md file. Follow the instructions to install and configure the FreeCAD MCP server on this machine.
The prompt from the README: the agent installs the workbench and dependencies and registers the server itself.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The arbitrary Python tool gives the agent filesystem and OS access through the FreeCAD environment
- Contents of open FreeCAD files reach the agent context: a file from an untrusted source can carry harmful instructions
This is third-party code. Review the repository files before installing.
What it does
The project has two parts: the AICopilot workbench, which runs a socket server inside FreeCAD, and a Python bridge that turns MCP calls into messages for that socket. The agent gets 41 tools for a running FreeCAD: Part, PartDesign, Sketch, Draft, boolean operations, transforms, measurements, meshes and CAM. Typical tasks from the README: build a mounting plate from dimensions, work out why a pad on a sketch fails, check wall thickness before printing, plan milling of a pocket, turn a manufacturer STL into a part with mounting features. Separate tools read the Report View, show sketch constraints and keep an operation log with crash reports from the OCCT kernel. The bridge can drive several FreeCAD instances, GUI and headless, each with its own socket and discovery file. The agent lists instances, picks one by label or UUID and can spawn a new one.
Who it is for. Designers, CNC machinists and 3D printing makers who want to drive FreeCAD work through a conversation with an agent.
Good fit when
- A part with dimensions and holes has to be built from a description and refined into a working model
- FreeCAD gives an unclear error on a pad or an external link and the agent should read the Report View
- Before printing or CNC you want to check walls, geometry errors and part collisions
- A series of identical brackets needs a macro that builds them from a dimension table
- The model must go to manufacturing as STEP and you want G-code for the router
Not a fit when
- You want to work with FreeCAD without the program running: the bridge talks only to a live instance with the workbench loaded
- FreeCAD files come from untrusted sources: the agent reads their contents and can run embedded code
- A simple Python script for FreeCAD is enough: the bridge is overkill if there is no dialogue with the model
Example request
In the open document build a 100x60 mm mounting plate with four M3 holes and rounded corners, then check the wall thickness.MCP
- Transport
- stdio
- Authentication
- not required
Limitations
All tools except CAM target stable FreeCAD 1.1.x, and CAM toolpaths need a recent weekly build. The author developed on macOS with Claude Code, and the code supports Windows and Linux with less testing. The package is not on PyPI: the mcp-agent-notes dependency is pinned to a commit, and installation follows the AGENT-INSTALL.md guide in the repository. Clients with a hard cap on tool count may not fit all 41. Once a day the bridge checks for a new release through the public GitHub API and logs it locally.
How to disable. Close FreeCAD or disable the AICopilot workbench in its addon manager and remove the freecad entry from the MCP client config. The cloned project folder can be deleted, it keeps no FreeCAD data.
FAQ
Which FreeCAD version is required?
Stable 1.1.x covers every tool except CAM. Toolpath generation needs a recent weekly development build, formerly called 1.2-dev.
What can the agent do on the system through this bridge?
The arbitrary Python tool runs code inside the FreeCAD environment, so it can reach the filesystem and the OS. The author calls this by design. Watch which calls you approve.
Can I connect several FreeCAD windows?
Yes. Every process has its own UUID, socket and discovery file. list_freecad_instances and select_freecad_instance show and pick an instance, and spawn_freecad_instance starts a new one.
Does the bridge work with clients other than Claude?
The author smoke-tested it by hand through the native MCP client of LM Studio with a local Qwen2.5 Coder 14B model. The main scenario is built on Claude Code, and patches for other agents are welcome.
What does the diagnostics log help with?
The bridge writes an operation log and keeps crash reports for OCCT kernel failures that leave no trace in FreeCAD itself. The AGENT-DEBUGGING.md guide gives the agent an investigation order.
Discussion
No questions or reviews yet.
Related
MCP serversClassCAD CAD MCP server: an agent builds parts and assemblies with scripts, views snapshots and saves STEP and STL
PartCAD keeps mechanical parts as text, so an agent writes the CAD script, renders the model and checks it against the brief.
MCP server for ITASCA geomechanics: an agent searches PFC, FLAC, 3DEC, MPoint and MassFlow docs and runs simulations
An MCP server for OpenSCAD: the agent renders parts at a known scale, measures geometry and finds collisions in assemblies
agentcad gives an AI agent 3D design: build123d scripts, STEP export, renders, geometry checks and a live browser preview
A CAD MCP server for build123d: the agent builds a part step by step, checks renders, measures geometry and exports STEP and STL.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| FreeCAD MCP: an AI agent in parametric CAD (this card) | no | not required | 66 | |
| FreeCAD MCP | no | not required | 3,310 | another FreeCAD MCP implementation, not this bridge with the AICopilot workbench |
| KiCad MCP Pro | no | not required | 212 | printed circuit board design in KiCad, mechanical modelling not covered |
README in short
The README frames the project as a design partner: the person sets the intent and the agent handles the FreeCAD mechanics. Two worked scenarios are shown, debugging an external reference and a shingle generator driven by a parameter table, along with sections on security and tests.