FreeCAD MCP
Provides tools for interacting with a live FreeCAD desktop session, enabling AI agents to create and edit 3D geometry, manage documents, capture screenshots of the 3D view, and export models to various formats.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@FreeCAD MCP Create a plate with four drilled holes and export as STEP."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
FreeCAD MCP
An MCP server that lets an AI agent drive a live FreeCAD desktop session — the model builds geometry, you watch it appear in the FreeCAD window, and the agent can screenshot the 3D view to check its own work.
Verified against FreeCAD 1.1.3 on macOS.
How it works
MCP client (opencode)
│ stdio / MCP
▼
freecad-mcp ← own uv venv, Python 3.10+, mcp SDK
│ XML-RPC on 127.0.0.1:9875
▼
FreeCADMCP addon ← runs inside FreeCAD's bundled Python 3.11
│ QTimer task queue
▼
FreeCAD GUI main thread ← documents, geometry, 3D viewTwo processes, deliberately. The MCP server never imports FreeCAD, so it can use a modern venv and any dependencies it likes, while the addon stays stdlib-only inside FreeCAD's interpreter.
The RPC server runs on a background thread, but every FreeCAD call is marshalled
onto the Qt main thread through a queue drained by a QTimer
(addon/FreeCADMCP/freecad_mcp_bridge/dispatcher.py). Touching FreeCAD documents from
a worker thread corrupts state or crashes the app, so this hop is not optional.
The wire protocol is a single call(method, payload_json) -> json endpoint. Passing
JSON through one method sidesteps every XML-RPC marshalling quirk (no None, no
nested heterogeneous types) and keeps errors as structured data instead of faults.
Related MCP server: FreeCAD Robust MCP Server
Setup
make install # create the venv, install dependencies
make addon-install # symlink the addon into FreeCAD's Mod directory
make freecad # start FreeCAD -- the bridge autostarts
make check # confirm the bridge answersmake check should print your FreeCAD version and open documents.
The addon is symlinked, not copied, so edits in this repo take effect on the next
FreeCAD restart (make freecad-restart).
Wiring it into opencode
opencode.json already registers the server. Restart opencode to pick it up —
config is read once at startup.
It uses "cwd": ".", which opencode resolves from the workspace directory, so there
is no absolute path to update when you clone this elsewhere.
timeout is raised to 120s because the 5s default is not enough for capture_view
or export_objects on a non-trivial model.
Other MCP clients
Clients without a workspace concept (Claude Desktop and friends) need an explicit
path — replace /absolute/path/to/FreeCAD-MCP with wherever you cloned this:
{
"mcpServers": {
"freecad": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/FreeCAD-MCP", "freecad-mcp"]
}
}
}Tools
Tool | Purpose |
| Connectivity check, FreeCAD version, open documents |
| Document management |
| Persistence and rebuild |
| Inspect the tree; |
| Typed geometry editing |
| Read what the user selected in the GUI |
| Execute Python inside FreeCAD (escape hatch) |
| Screenshot the 3D view, returned as an image |
| STEP, IGES, STL, OBJ, PLY, 3MF, AMF, OFF, BREP, FCStd |
Value formats
create_object and edit_object accept JSON and coerce it to FreeCAD's native types:
Property kind | Accepted |
lengths |
|
vectors |
|
placement |
|
rotation |
|
links |
|
colours |
|
Angles are degrees, lengths millimetres.
view_properties targets the ViewObject: ShapeColor, Transparency (0–100),
DisplayMode, Visibility.
Example
Creating a plate with four drilled holes:
create_object type_id="Part::Box" properties={"Length":60,"Width":40,"Height":10}
create_object type_id="Part::Cylinder" properties={"Radius":3,"Height":20,
"Placement":{"Base":[10,10,-5]}}
create_object type_id="Part::Cut" properties={"Base":"Box","Tool":"Cylinder"}
capture_view # look at it before declaring success
export_objects path="~/plate.step"Configuration
Variable | Default | Applies to |
|
| both |
|
| both |
|
| MCP server |
|
| addon |
The addon also reads FreeCAD parameters under
BaseApp/Preferences/Mod/FreeCADMCP (Host, Port, AutoStart), editable via
Tools > Edit parameters. Environment variables win.
The bridge binds to loopback only and has no authentication — anything that can reach
the port can execute arbitrary Python in FreeCAD. Do not expose it beyond 127.0.0.1.
Bridge controls in FreeCAD
The addon adds an MCP workbench with Start / Stop / Status commands. The bridge autostarts 1.5s after the GUI is up, and stops cleanly on quit.
Development
make smoke # end-to-end test through a real MCP client (FreeCAD must run)
make lint # ruff
make freecad-restart # reload addon changes
make addon-status # is the addon linked?make smoke exercises all 18 tools against a live session and verifies boolean
geometry numerically (a drilled plate's volume must match l·w·h − nπr²h).
Two FreeCAD gotchas this codebase works around
1. InitGui.py has no usable module scope. FreeCAD runs it via exec from
inside a function, so top-level names become that function's locals. Any function or
class method defined in InitGui.py resolves its globals against FreeCAD's own init
module and dies with NameError. All logic therefore lives in
freecad_mcp_bridge/workbench.py, which is imported normally; InitGui.py is a
five-line shim.
2. package.xml decides where FreeCAD looks for your code. When a workbench
entry omits <subdirectory>, FreeCAD defaults it to the workbench <name> — so a
workbench named MCP makes FreeCAD search FreeCADMCP/MCP/InitGui.py and silently
skip the addon. Hence the explicit <subdirectory>./</subdirectory>.
A third, smaller one: in FreeCAD 1.x, ShapeColor is a Python shim over
ShapeAppearance rather than a registered property, so getTypeIdOfProperty fails
for it. serialize.py falls back to inferring the type from the value currently
stored.
Layout
addon/FreeCADMCP/ installed into FreeCAD's Mod directory
InitGui.py thin shim (see gotcha 1)
package.xml addon metadata (see gotcha 2)
freecad_mcp_bridge/
workbench.py workbench, commands, autostart
server.py XML-RPC server + JSON envelope
dispatcher.py background thread -> Qt main thread
handlers.py the FreeCAD operations
serialize.py JSON <-> FreeCAD type conversion
src/freecad_mcp/
server.py MCP tool definitions
client.py XML-RPC client
__main__.py CLI entry point
scripts/smoke.py end-to-end testTroubleshooting
make check says the bridge is unreachable. Confirm FreeCAD is running, the addon
is linked (make addon-status), and check FreeCAD's View > Panels > Report view for
[FreeCAD MCP] messages.
Address already in use on startup. A previous FreeCAD process still holds the
port — make freecad-quit force-kills leftovers.
Addon changes have no effect. The addon is imported once at startup; run
make freecad-restart.
A tool times out. Something is blocking FreeCAD's main thread, usually a modal dialog. Dismiss it in the GUI.
Available Tools
18 toolscapture_viewA
Screenshot the 3D view and return it as an image.
Always look at the model after building geometry instead of assuming it is correct.
Args: document: defaults to the active document. view: axonometric, isometric, front, rear, left, right, top or bottom. width, height: pixel size of the render. fit: zoom to fit all visible geometry first.
Inputs: fit, view, width, height, +1 more.
close_documentB
Close a document, optionally saving it first. Unsaved changes are lost.
Inputs: save, document. Returns: object
create_documentA
Create a new document and make it active.
Args: name: internal name; FreeCAD may append digits to keep it unique. label: optional display name shown in the tree.
Inputs: name, label. Returns: object
create_objectA
Create an object in a document.
Frequently used TypeIds: Primitives Part::Box (Length,Width,Height) | Part::Cylinder (Radius,Height,Angle) Part::Sphere (Radius) | Part::Cone (Radius1,Radius2,Height) Part::Torus (Radius1,Radius2) | Part::Plane (Length,Width) Part::Wedge | Part::Ellipsoid | Part::Prism (Polygon,Circumradius,Height) Booleans Part::Cut / Part::Fuse / Part::Common (properties: Base, Tool) Part::MultiFuse / Part::MultiCommon (property: Shapes = [names]) Transforms Part::Mirroring (Source,Normal,Base) | Part::Extrusion | Part::Revolution Structure App::Part | App::DocumentObjectGroup | App::Link (LinkedObject) Modelling PartDesign::Body | Sketcher::SketchObject (build these with run_python)
Value formats accepted by properties:
numbers/lengths 10 or 10.5 (millimetres)
vectors [x, y, z] or {"x":.., "y":.., "z":..}
placement {"Base":[x,y,z], "Rotation":{"Axis":[0,0,1], "Angle":45}}
rotation 45 (degrees about Z) | {"Axis":[..],"Angle":..} | {"Yaw":..,"Pitch":..,"Roll":..}
links "Box" (object Name or Label) link lists: ["Box","Cylinder"]
colours "#ff8800" | [1.0, 0.53, 0.0] | [255, 133, 0]
view_properties targets the ViewObject: ShapeColor, Transparency (0-100),
DisplayMode ("Flat Lines","Shaded","Wireframe"), Visibility.
Example: a 20mm cube offset on X, coloured orange type_id="Part::Box" properties={"Length": 20, "Width": 20, "Height": 20, "Placement": {"Base": [30, 0, 0]}} view_properties={"ShapeColor": "#ff8800"}
Example: cut a cylinder out of a box (both must already exist) type_id="Part::Cut", properties={"Base": "Box", "Tool": "Cylinder"}
Inputs: type_id (required), name, label, document, +2 more. Returns: object
delete_objectA
Delete an object.
Args: recursive: also delete the object's children (e.g. the operands consumed by a boolean). Deleting a boolean without this leaves its operands behind.
Inputs: name (required), document, recursive. Returns: object
edit_objectA
Change properties of an existing object.
Only the properties you pass are touched; everything else is left alone.
Call get_object first if you are unsure which properties exist.
Value formats accepted by properties:
numbers/lengths 10 or 10.5 (millimetres)
vectors [x, y, z] or {"x":.., "y":.., "z":..}
placement {"Base":[x,y,z], "Rotation":{"Axis":[0,0,1], "Angle":45}}
rotation 45 (degrees about Z) | {"Axis":[..],"Angle":..} | {"Yaw":..,"Pitch":..,"Roll":..}
links "Box" (object Name or Label) link lists: ["Box","Cylinder"]
colours "#ff8800" | [1.0, 0.53, 0.0] | [255, 133, 0]
view_properties targets the ViewObject: ShapeColor, Transparency (0-100),
DisplayMode ("Flat Lines","Shaded","Wireframe"), Visibility.
Inputs: name (required), label, document, properties, +1 more. Returns: object
export_objectsB
Export geometry to a file; the format comes from the extension.
Supported: .step/.stp, .iges/.igs, .stl, .obj, .ply, .3mf, .amf, .off, .brep and .fcstd.
Args: path: destination file path. objects: object names to export; omit to export every shaped object.
Inputs: path (required), objects, document. Returns: object
freecad_statusA
Check the bridge connection and list open documents.
Call this before anything else. It reports the FreeCAD version, which document is active, and how many objects each open document holds.
Inputs: no named parameters. Returns: object
get_objectA
Inspect one object: all properties, plus shape volume/area/bounding box.
Args: name: object Name or Label. include_properties: set False for a lighter response on complex objects. include_shape: set False to skip geometry measurement.
Inputs: name (required), document, include_shape, include_properties. Returns: object
get_selectionA
Read what the user currently has selected in the FreeCAD GUI.
Useful when the user says "this part" or "the selected face".
Inputs: no named parameters. Returns: object
list_documentsA
List every open FreeCAD document with its file path and modified state.
Inputs: no named parameters. Returns: object
list_objectsA
List objects in a document (name, label, TypeId, state).
Args: document: defaults to the active document. type_filter: case-insensitive substring match on TypeId, e.g. "Part::" or "Sketch".
Inputs: document, type_filter. Returns: object
move_objectA
Reposition an object without touching its other properties.
Args: name: object Name or Label. position: absolute [x, y, z] in mm. Omit to keep the current position. rotation: degrees about Z, or {"Axis": [x,y,z], "Angle": deg}, or {"Yaw":.., "Pitch":.., "Roll":..}. Omit to keep the current rotation.
Inputs: name (required), document, position, rotation. Returns: object
open_documentA
Open an existing .FCStd file and make it active.
Inputs: path (required). Returns: object
recomputeA
Recompute a document and report objects left in an error/invalid state.
Use this after run_python or when geometry looks stale.
Inputs: force, document. Returns: object
reset_pythonA
Clear variables accumulated by previous run_python calls.
Inputs: no named parameters. Returns: object
run_pythonA
Execute Python inside FreeCAD. The escape hatch for anything the typed tools cannot do.
Preloaded names: App/FreeCAD, Gui/FreeCADGui, and doc (the active
document). Globals persist between calls, so you can build state incrementally.
A trailing expression is returned like a REPL; in statement mode, assign to
result to return a value. The document is recomputed afterwards.
Returns stdout, stderr, the value, and a full traceback on failure.
Example -- a sketch-based pad: body = doc.addObject("PartDesign::Body", "Body") sketch = body.newObject("Sketcher::SketchObject", "Sketch") import Part sketch.addGeometry(Part.Circle(App.Vector(0,0,0), App.Vector(0,0,1), 10), False) pad = body.newObject("PartDesign::Pad", "Pad") pad.Profile = sketch pad.Length = 25 result = pad.Name
Inputs: code (required), document. Returns: object
save_documentA
Save a document.
Args: document: document name; defaults to the active one. path: save to this path instead (required the first time a document is saved).
Inputs: path, document. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Each tool targets a distinct resource and action: document lifecycle (create/open/save/close/list), object inspection/manipulation (list/get/create/edit/move/delete), and utility operations (recompute, selection, status, python, view, export). The only minor overlap is freecad_status vs list_documents, but their descriptions clearly differentiate bridge health/version info from detailed document listing.
The vast majority of tools follow a verb_noun snake_case pattern (create_document, get_object, delete_object, export_objects). Two deviations exist: recompute is verb-only, and freecad_status is noun_status rather than get_freecad_status. These are minor and do not impede readability.
18 tools for a CAD server is on the higher end but appropriate given the breadth of modeling, document, and utility operations. Each tool serves a distinct function, and the count is not bloated with redundant entries. It is slightly above the ideal 3-15 range but still well-scoped.
The tool surface covers full CRUD for documents and objects, plus essential utilities like recompute, selection, rendering, and export. Advanced parametric modeling (e.g., sketches, pads) is delegated to run_python, which acts as a well-documented escape hatch. Minor gaps like object duplication or renaming are workable via the Python escape hatch.
Maintenance
Related MCP Connectors
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables to control FreeCAD from Claude Desktop through MCP, allowing CAD operations like creating and editing objects, taking screenshots, and executing Python code.111MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with FreeCAD for 3D modeling, macros, and debugging via MCP.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to programmatically build, analyze, and export 3D CAD geometry using FreeCAD through REST or MCP tools.MIT
- AlicenseAqualityBmaintenanceAI pilots FreeCAD. Provides full control of FreeCAD for parametric modeling, assembly, geometry sensing, and more via MCP tool calls.2797 PyPI26MIT