Skip to main content
Glama
freecad-mcp-headless

freecad-mcp-headless

by pitbuild

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.

Example render

screenshot output for a 10 × 20 × 30 mm block: orthographic, flat-shaded, annotated — produced without a display, GPU or OpenGL.

How it works

  1. The server binds a TCP port on 127.0.0.1, generates a one-time token and starts freecadcmd.

  2. The worker connects back, proves the token and then serves JSON lines: one request, one reply.

  3. Documents stay open in that worker, so open_document → measure → export_document costs one FreeCAD startup, not three.

  4. A call that exceeds --timeout kills 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 /tmp

MCP 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

freecad_info

Version, Python version, worker PID, loaded documents

open_document

Open .FCStd, .step, .stp, .iges, .igs, .brep, .stl, .obj

list_documents / close_document

Session bookkeeping

inspect_document

Objects, types, visibility, key properties, feature timeline

measure

Volume, surface area, bounding box, centre of mass, face/edge/vertex counts

bounding_box

Compact size report in mm

export_document

STEP, IGES, BREP, STL, OBJ, 3MF, DXF, SVG, AMF

save_document

Save as .FCStd, optionally with a copy

parameters / set_parameter

Read and drive FreeCAD expressions, then rebuild

recompute

Re-evaluate the document timeline

execute_python

Run trusted host Python inside the worker (optional, not sandboxed)

screenshot

Flat-shaded PNG or dependency-free SVG without a GPU or display

worker_status / restart_worker

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-only exposes inspection/measurement and open/close session bookkeeping only; removes save, export, screenshot (both write files), parameter changes, recompute, restart and arbitrary Python.

  • --no-execute removes the execute_python tool entirely.

  • The worker never listens on a public interface: the TCP socket binds 127.0.0.1 on 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

worker_unavailable: FreeCAD did not connect back in time

wrong binary, missing libs

run freecadcmd --version; check the log tail in the error

rejected: file extension ...

guard refused the format

see the allowed lists in SECURITY.md

renderer_unavailable

no matplotlib in FreeCAD's Python

write .svg instead, or install matplotlib for that interpreter

unknown_document

FreeCAD rewrites file stems (fc-smoke → fc_smoke)

pass the name from the open_document reply, or the label

STEP opens as an empty document

a mesh-only STL was opened as a solid

use screenshot/measure on meshes, not export to STEP

Requirements

  • Python 3.10+

  • FreeCAD 0.20+ with freecadcmd on PATH, or set FREECADCMD=/path/to/freecadcmd

  • PNG screenshots need matplotlib importable 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 example sudo apt install python3-matplotlib on 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. Check freecad_info for the worker Python version and validate by calling screenshot with a .png target. If unavailable, it returns renderer_unavailable: use a .svg target, 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 freecadcmd

License

MIT

Available Tools

16 tools
bounding_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

    B3.1/5.0

    Scored across 16 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • 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
    • F
      license
      Not graded
      quality
      D
      maintenance
      An 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
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI clients to create, edit, and export CAD models and drawings in a locally installed FreeCAD via MCP.
      3
      -
    • A
      license
      A
      quality
      B
      maintenance
      Gives 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.
      5
      MIT