freecad-mcp-headless
Provides an MCP server for headless FreeCAD, enabling opening and inspecting CAD documents, measuring geometry, changing parameters, recomputing feature trees, exporting models, and rendering screenshots without a GUI or X server.
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-headless open /tmp/bracket.step and tell me its bounding box in mm"
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-headless
An MCP (Model Context Protocol) server for headless FreeCAD — no GUI, no X server, no RPC add-on.
It drives the official freecadcmd binary through a persistent worker process, so a document is opened
once and stays open across tool calls. Everything FreeCAD can script, this server can expose:
.FCStd documents, STEP/IGES import and export, measurements, parameter changes, feature trees,
mesh export and PNG renders.
MCP client <--stdio--> freecad-mcp-headless <--TCP--> freecadcmd worker (persistent)Why
FreeCAD ships a full Python API but no MCP server. The community MCP projects require a running
FreeCAD GUI with an RPC socket, which rules out servers and containers. This project has no GUI
dependency at all: it starts freecadcmd, keeps one worker alive, and speaks a small JSON protocol
over loopback TCP.
Related MCP server: mcpfreecad
Status
Working and tested against FreeCAD 1.1.4 on Linux, plus a CI job that runs the integration suite on
every push. See PLAN.md for the build plan and docs/TOOLS.md for the tool reference.

screenshot output for a 10 × 20 × 30 mm block: orthographic, flat-shaded, annotated — produced
without a display, GPU or OpenGL.
How it works
The server binds a TCP port on
127.0.0.1, generates a one-time token and startsfreecadcmd.The worker connects back, proves the token and then serves JSON lines: one request, one reply.
Documents stay open in that worker, so
open_document→measure→export_documentcosts one FreeCAD startup, not three.A call that exceeds
--timeoutkills the worker; the next call starts a new one. A crash is detected the same way, and the log tail is attached to the error.
Because FreeCAD's console build has no OpenGL, screenshot renders the tessellated geometry in
software (matplotlib for PNG, a built-in writer for SVG). That is also why the tool never needs an
X server.
Quick start
pip install -e .
freecad-mcp-headless --allow-path ~/cad --allow-path /tmpMCP client configuration (mcporter / Claude Desktop / any stdio MCP client):
{
"mcpServers": {
"freecad": {
"command": "freecad-mcp-headless",
"args": ["--allow-path", "/root/cad-work"]
}
}
}Tools
Tool | What it does |
| Version, Python version, worker PID, loaded documents |
| Open |
| Session bookkeeping |
| Objects, types, visibility, key properties, feature timeline |
| Volume, surface area, bounding box, centre of mass, face/edge/vertex counts |
| Compact size report in mm |
| STEP, IGES, BREP, STL, OBJ, 3MF, DXF, SVG, AMF |
| Save as |
| Read and drive FreeCAD expressions, then rebuild |
| Re-evaluate the document timeline |
| Run trusted host Python inside the worker (optional, not sandboxed) |
| Flat-shaded PNG or dependency-free SVG without a GPU or display |
| Health and recovery |
Full parameter documentation: docs/TOOLS.md.
Safety
Path allow-list: every path argument must resolve inside a directory passed with
--allow-path. Symlinks are resolved first, so../and link escapes are rejected.Extension allow-list per operation.
Input file size guard (
--max-file-size, default 256 MiB); also checks existing write targets, but is not a generated-output quota.Per-call timeout (
--timeout, default 120 s); a hung call restarts the worker.--read-onlyexposes inspection/measurement and open/close session bookkeeping only; removes save, export, screenshot (both write files), parameter changes, recompute, restart and arbitrary Python.--no-executeremoves theexecute_pythontool entirely.The worker never listens on a public interface: the TCP socket binds
127.0.0.1on an ephemeral port and requires a random token in the handshake.
Read SECURITY.md before exposing the server to an untrusted client.
Notes for MCP clients
A stdio MCP client keeps one server process alive for the whole session — that is the mode this server is designed for, and documents stay open between calls.
One-shot CLI wrappers (mcporter call and friends) start a fresh process per call unless they run a
daemon, so the document list is empty on every invocation there. Call open_document and the
follow-up tool in the same session, or run the whole job through execute_python in a single call.
Troubleshooting
Symptom | Cause | Fix |
| wrong binary, missing libs | run |
| guard refused the format | see the allowed lists in |
| no matplotlib in FreeCAD's Python | write |
| FreeCAD rewrites file stems ( | pass the name from the |
STEP opens as an empty document | a mesh-only STL was opened as a solid | use |
Requirements
Python 3.10+
FreeCAD 0.20+ with
freecadcmdonPATH, or setFREECADCMD=/path/to/freecadcmdPNG screenshots need
matplotlibimportable by FreeCAD's embedded Python.pip install -e ".[render]"only installs it into the server environment, which the worker does not use. For a distro FreeCAD using system Python, install the matching distro package (for examplesudo apt install python3-matplotlibon Debian/Ubuntu). Bundled/AppImage builds need a compatible package installed for their own embedded Python; system or server-venv packages may not be ABI-compatible. Checkfreecad_infofor the worker Python version and validate by callingscreenshotwith a.pngtarget. If unavailable, it returnsrenderer_unavailable: use a.svgtarget, whose built-in renderer needs no optional packages.
Development
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev,render]"
pytest -m "not integration" # unit tests, no FreeCAD needed
pytest -m integration # needs freecadcmdLicense
MIT
Available Tools
16 toolsbounding_boxB
Return the bounding box size, minimum, maximum and centre in millimetres.
Inputs: document.
close_documentB
Close a document; without an argument the active document is closed.
Inputs: document.
execute_pythonA
Run Python inside the FreeCAD worker and return stdout plus result.
The document is available as doc, the FreeCAD module as FreeCAD
(alias App). Assign to a variable named result to return data.
This tool is the escape hatch for anything the other tools do not cover;
it can be disabled on the server with --no-execute.
Inputs: code (required), document.
export_documentB
Export the document geometry to STEP, IGES, BREP, STL, OBJ, 3MF, DXF, SVG, AMF or FCStd.
The format is inferred from the file extension unless format is given.
Returns the written path, format and byte size.
Inputs: path (required), format, document.
freecad_infoA
Report the FreeCAD build, worker process and open documents.
Starts the worker on the first call. Use this to verify a working install.
Inputs: no named parameters.
inspect_documentC
Describe a document: objects, types, key properties, expressions and timeline order.
Each object reports volume, area, bounding box, solid/face/edge counts and any parametric expressions that drive it.
Inputs: document.
list_documentsA
List every document in the worker with its file path and modification state.
Inputs: no named parameters.
measureB
Measure geometry in millimetres.
Returns volume (mm3), surface area (mm2), centre of mass, bounding box,
diagonal and face/edge/vertex counts — per object and summed. Pass
objects to restrict the measurement to selected object names.
Inputs: objects, document.
open_documentB
Open a CAD file and make it the active document.
Supports .FCStd, .step/.stp, .iges/.igs, .brep, .stl, .obj, .3mf, .dxf, .svg, .amf. The file must live inside an allowed directory. Returns the document name, object count and the FreeCAD types it contains.
Inputs: path (required), name.
parametersC
List every parametric expression and spreadsheet alias in the document.
Inputs: document.
recomputeC
Re-evaluate the document timeline after external changes.
Inputs: document.
restart_workerA
Restart the FreeCAD process. Open documents are lost unless saved.
Inputs: no named parameters.
save_documentC
Save the document to disk, optionally to a new .FCStd path.
Inputs: path, document.
screenshotB
Render the model to a PNG (or SVG) without a display or GPU.
Views: iso, front, back, left, right, top, bottom. The image is an orthographic, flat-shaded projection of the tessellated geometry, annotated with the bounding-box size in millimetres.
Inputs: path (required), view, width, height, +1 more.
set_parameterB
Set a parameter and rebuild the model.
reference is either Object.Property (for example Box.Length) or a
spreadsheet alias. value is a number or a FreeCAD expression such as
40 mm or Box.Length * 2.
Inputs: value (required), reference (required), document.
worker_statusA
Report worker health, PID, FreeCAD version and the tail of its log.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Most tools are distinct, but inspect_document already returns volume, area, bounding box, properties and expressions, overlapping heavily with measure, bounding_box and parameters. Likewise freecad_info and worker_status both report FreeCAD version and worker state, so agents must rely on the descriptions to pick the right one.
Nearly all names are snake_case and follow a verb_noun pattern (open_document, close_document, set_parameter, export_document, execute_python). A few deviate as bare nouns or single verbs (parameters, screenshot, measure, recompute, bounding_box), which is a minor inconsistency but still readable.
16 tools is just over the ideal band but each covers a distinct CAD workflow step (open/close/save/export, inspect, measure, parameterize, render, worker control). Nothing looks padded, though a couple of read tools could plausibly be merged.
The surface covers document lifecycle, inspection, measurement, parameter editing and export, but there is no structured way to create a document or add/delete/transform geometry — modifications beyond parameter edits require the execute_python escape hatch. That is workable but leaves notable gaps for agents that cannot rely on raw Python.
Maintenance
Related MCP Connectors
Headless CAD engine & MCP server for 2D/3D drafting, solids, DXF/SVG export, and automation.
Free 3D conversion (FBX, GLB, OBJ, STL, PLY, DAE, USDZ, 3MF) as a remote MCP server. No account.
Fast multi-format CAD previews, geometry checks and conversion; measure and share in the workspace.
Hosted MCP server for task-first delegation to remote workstations and workers.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to programmatically build, analyze, and export 3D CAD geometry using FreeCAD through REST or MCP tools.MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that drives a running FreeCAD session, exposing document management, modeling, inspection, snapshot, and optional workbench operations to MCP clients over stdio or authenticated remote HTTP.2-
- FlicenseNot gradedqualityCmaintenanceEnables AI clients to create, edit, and export CAD models and drawings in a locally installed FreeCAD via MCP.3-
- AlicenseAqualityBmaintenanceGives MCP clients headless access to FreeCAD so they can inspect models for dimensions, validity and watertightness, convert between CAD and mesh formats like STEP, STL, 3MF, IGES and BREP, extract 2D DXF/SVG profiles for laser cutting, and run FreeCAD Python scripts for automation and CI.5MIT