Skip to main content
Glama
FreeCAD MCP

FreeCAD MCP

by ahelja

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 view

Two 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 answers

make 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

freecad_status

Connectivity check, FreeCAD version, open documents

list_documents / create_document / open_document

Document management

save_document / close_document / recompute

Persistence and rebuild

list_objects / get_object

Inspect the tree; get_object reports volume, area, bounding box

create_object / edit_object / move_object / delete_object

Typed geometry editing

get_selection

Read what the user selected in the GUI

run_python / reset_python

Execute Python inside FreeCAD (escape hatch)

capture_view

Screenshot the 3D view, returned as an image

export_objects

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

10, 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" — an object Name or Label

colours

"#ff8800", [1.0, 0.53, 0.0], or [255, 133, 0]

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

FREECAD_MCP_HOST

127.0.0.1

both

FREECAD_MCP_PORT

9875

both

FREECAD_MCP_TIMEOUT

300 (seconds)

MCP server

FREECAD_MCP_AUTOSTART

1

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 test

Troubleshooting

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 tools
capture_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

    A3.9/5.0

    Scored across 18 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables to control FreeCAD from Claude Desktop through MCP, allowing CAD operations like creating and editing objects, taking screenshots, and executing Python code.
      11
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to programmatically build, analyze, and export 3D CAD geometry using FreeCAD through REST or MCP tools.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      AI pilots FreeCAD. Provides full control of FreeCAD for parametric modeling, assembly, geometry sensing, and more via MCP tool calls.
      27
      97 PyPI
      26
      MIT