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

## Start the bridge in FreeCAD

The Codex plugin is the MCP client. FreeCAD also needs the bundled
`Robust MCP Bridge` workbench running; installing the Codex plugin alone does
not start the FreeCAD-side server.

1. Install the addon folder `freecad-addon/RobustMCPBridge` into FreeCAD's
   user `Mod` directory. For FreeCAD 1.1 on Windows, use
   `%APPDATA%\FreeCAD\v1-1\Mod\RobustMCPBridge`. Create the `Mod` directory
   if it does not exist, then copy the whole `RobustMCPBridge` folder there.
2. Restart FreeCAD so it loads the workbench.
3. In the workbench selector, choose **Robust MCP Bridge**.
4. Click **Start MCP Bridge** in its toolbar, or run
   **Robust MCP Bridge → Start MCP Bridge** from the menu.
5. The default Codex connection uses XML-RPC at `localhost:9875`. The workbench
   status command or status-bar indicator should show the bridge as running.
6. In Codex, call `freecad_health`; it should report `connected: true`. If the
   MCP server was started before FreeCAD, restart the FreeCAD MCP server from
   Codex after starting the bridge.

To start the bridge automatically with FreeCAD, open
**Edit → Preferences → Robust MCP Bridge**, enable **Auto-start bridge when
FreeCAD launches**, and apply the setting. Auto-start is off by default. The
same preferences page lets you change the XML-RPC port; keep it at `9875`
unless `FREECAD_XMLRPC_PORT` in the Codex MCP configuration is changed to the
same value.

For a quick local port check in PowerShell, run:

```powershell
Test-NetConnection 127.0.0.1 -Port 9875
```

The bridge listens on localhost. Do not expose its ports to other machines.

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.