Skip to main content
Glama
freecad-mcp-headless

freecad-mcp-headless

by pitbuild

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
timeoutNoPer-call timeout in seconds (default 120 s). A hung call restarts the worker.
read-onlyNoExpose inspection/measurement and open/close session bookkeeping only; removes save, export, screenshot, parameter changes, recompute, restart and arbitrary Python. Set to 'true' to enable.
FREECADCMDNoPath to the freecadcmd binary if not on PATH.
allow-pathNoDirectory to allow for path arguments. Every path argument must resolve inside a directory passed with --allow-path. Can be specified multiple times.
no-executeNoRemove the execute_python tool entirely. Set to 'true' to enable.
max-file-sizeNoMaximum input file size in bytes (default 256 MiB).

Instructions

Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.

This server publishes no instructions, or was last inspected before Glama recorded them.

Capabilities

Features and capabilities supported by this server

Protocol revision2025-11-25

CapabilityDetails
tools
{
  "listChanged": false
}
prompts
{
  "listChanged": false
}
resources
{
  "subscribe": false,
  "listChanged": false
}
experimental
{}

Tools

Functions exposed to the LLM to take actions

NameDescription
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.

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.

list_documentsA

List every document in the worker with its file path and modification state.

close_documentB

Close a document; without an argument the active document is closed.

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.

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.

bounding_boxB

Return the bounding box size, minimum, maximum and centre in millimetres.

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.

save_documentC

Save the document to disk, optionally to a new .FCStd path.

parametersC

List every parametric expression and spreadsheet alias in the document.

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.

recomputeC

Re-evaluate the document timeline after external changes.

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.

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.

worker_statusA

Report worker health, PID, FreeCAD version and the tail of its log.

restart_workerA

Restart the FreeCAD process. Open documents are lost unless saved.

Prompts

Interactive templates invoked by user choice

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

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