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 under its MIT license. See LICENSE-CODE and UPSTREAM-NOTICE.md.

Development setup

git clone https://github.com/hashbolic/Codex-FreeCAD-MCP.git
Set-Location Codex-FreeCAD-MCP
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e . pytest

Install the bundled freecad-addon/RobustMCPBridge package into FreeCAD's user Mod directory, restart FreeCAD, select the Robust MCP Bridge workbench, and start its XML-RPC bridge on localhost:9875. FreeCAD.getUserAppDataDir() in the FreeCAD Python console reports the correct per-user base directory.

The repository root is a Codex plugin (.codex-plugin/plugin.json) and its .mcp.json launches the local .venv. Add this checkout to a configured local Codex plugin marketplace, then install freecad-mcp-codex from that marketplace.

Run the offline release checks with:

.\.venv\Scripts\python.exe -m pytest -q -k "not live"

The complete release gate also requires a running FreeCAD bridge and a BC250 fixture through FREECAD_TEST_XMLRPC_PORT and FREECAD_BC250_PATH.

Related MCP server: freecad-mcp

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.

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.