FreeCAD MCP for Codex
# FreeCAD MCP for Codex
This local Codex plugin exposes a compact typed MCP surface for FreeCAD 1.1.x
on Windows. It connects to the bundled Robust MCP Bridge over XML-RPC by
default and can also run with the embedded bridge when launched by FreeCAD's
Python 3.11 runtime.
The bridge implementation and FreeCAD addon are derived from
[spkane/freecad-addon-robust-mcp-server](https://github.com/spkane/freecad-addon-robust-mcp-server)
under its MIT license. See `LICENSE-CODE` and `UPSTREAM-NOTICE.md`.
## Configuration
Set `FREECAD_MODE=xmlrpc` (default), `FREECAD_XMLRPC_PORT=9875`, and start the
bundled addon inside FreeCAD. `FREECAD_ALLOW_EXECUTE_PYTHON=true` is required
for the controlled escape hatch; it is disabled by default.
The MCP server intentionally starts even when FreeCAD is offline, so
`freecad_health` can report a structured disconnected state. The bundled MCP
configuration uses the root-relative `freecad_mcp_codex.cmd` launcher, which
invokes `python -m freecad_mcp_codex.server` from the plugin root and remains
relocatable when copied without the development virtual environment.
Live XML-RPC tests are opt-in through `FREECAD_TEST_XMLRPC_PORT`. Release CI
should also set `FREECAD_REQUIRE_LIVE_TESTS=true` so a missing live bridge is a
hard failure rather than a skip.
The positive release gate can launch an isolated bridge and run the live suite:
`pwsh -File tests/run_live_gate.ps1`. Set `FREECAD_TEST_FREECAD` when FreeCAD is
installed outside `C:\Program Files\FreeCAD 1.1\bin\FreeCADCmd.exe`. Ordinary
developer runs continue to skip live tests when no bridge is available.
## Security boundary
This is a trusted-local integration. Keep the MCP process and FreeCAD XML-RPC
bridge bound to localhost. Only enable `execute_freecad_python` for code you
authored and understand: it can read and write local files, mutate open
documents, and use any capabilities available to the FreeCAD Python runtime.
Do not expose the bridge or MCP stdio process to untrusted users or networks.
TDQS
Scored across 36 tools
Most tools target distinct resources and actions, so an agent can usually tell them apart. A few pairs overlap in scope — inspect_shape and get_bounding_box both return bounds, and split_by_plane and split_for_print_bed both split shapes — but the descriptions make the intended use reasonably clear.
The set is predominantly lower_snake_case with an action+object pattern like list_documents, create_box, and export_step. It is not perfect because freecad_health is a noun-style outlier and the boolean_* tools use an adjective prefix instead of a clear verb.
At 36 tools this is well past the 25+ threshold for an over-large set, and several niche print-preparation helpers such as screw boss, heatset boss, fan mount, vent pattern, and print-bed splitter broaden the surface beyond a tight CAD API. The count is not an extreme 50+ disaster, but it should be trimmed or consolidated for a more focused server.
The set covers document lifecycle, object inspection, primitive modeling, boolean operations, filleting/chamfering, splitting, and STEP/STL import/export, so the primary solid-modeling workflow is usable. Missing first-class operations like delete/rename/copy objects and any sketch/extrude/parametric capabilities leave notable gaps for general FreeCAD use, partially papered over by execute_freecad_python.