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.

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.