Skip to content

Connection Modes

The FreeCAD Robust MCP Server supports multiple ways to connect to FreeCAD. Choose the mode that best fits your workflow.

Overview

Mode Description Platform Best For
xmlrpc XML-RPC protocol (port 9875) All platforms Production use (recommended)
socket JSON-RPC over TCP sockets All platforms Alternative to XML-RPC
embedded FreeCAD imported into MCP process Linux only Fastest execution, CI/automation

Security Boundary

The XML-RPC and socket bridges listen on loopback and require pairing with the MCP server before accepting requests. A paired client can execute Python inside FreeCAD. Pairing does not protect against malicious programs running as the same operating-system user. Non-loopback and remote bridge connections are not supported.

Docker Desktop can forward host.docker.internal to a host-loopback listener. Docker Engine on Linux cannot: its host-gateway address is outside the host loopback interface. For Linux GUI use, run the MCP server directly on the host.

XML-RPC mode is the default and recommended connection method when FREECAD_MODE and --mode are unset. It works on all platforms and provides robust, reliable communication. Pair the MCP server and bridge as described in the installation guide.

How It Works

MCP Client <--stdio--> Robust MCP Server <--XML-RPC:9875--> FreeCAD

The Robust MCP Server communicates with FreeCAD via XML-RPC protocol on port 9875.

Setup

  1. Start FreeCAD with the Robust MCP Bridge workbench
  2. Click Start Bridge (or it auto-starts if configured)
  3. Configure the Robust MCP Server:
export FREECAD_MODE=xmlrpc
export FREECAD_XMLRPC_PORT=9875  # default
freecad-mcp

Advantages

  • Works on all platforms (macOS, Linux, Windows)
  • Process isolation (FreeCAD crash doesn't affect Robust MCP Server)
  • Supports both GUI and headless FreeCAD

Socket Mode

Socket mode uses JSON-RPC over TCP sockets instead of XML-RPC.

How It Works

MCP Client <--stdio--> Robust MCP Server <--JSON-RPC:9876--> FreeCAD

Setup

export FREECAD_MODE=socket
export FREECAD_SOCKET_HOST=localhost
export FREECAD_SOCKET_PORT=9876
freecad-mcp

Advantages

  • JSON-based protocol (easier to debug)
  • Lower overhead than XML-RPC
  • Works on all platforms

Embedded Mode (Linux Only)

Platform Limitation

Embedded mode only works on Linux. On macOS and Windows, it causes crashes due to Python ABI incompatibility.

Embedded mode imports FreeCAD directly into the Robust MCP Server process, providing the fastest execution. It is an explicit opt-in: set FREECAD_MODE=embedded or pass --mode embedded.

Why It Crashes on macOS/Windows

FreeCAD's FreeCAD.so library links to @rpath/libpython3.11.dylib (FreeCAD's bundled Python). When you try to import it from a different Python interpreter (even the same version), it causes a crash because the Python runtime state is incompatible.

Setup (Linux Only)

export FREECAD_MODE=embedded
export FREECAD_PATH=/usr/lib/freecad/lib  # Adjust for your system
freecad-mcp

Advantages

  • Fastest execution (no IPC overhead)
  • No need to start FreeCAD separately
  • Works in CI/CD environments on Linux

Limitations

  • Linux only - crashes on macOS and Windows
  • Headless only (no GUI features)
  • Minimal testing - embedded mode receives less testing than xmlrpc/socket modes
  • Cannot access FreeCAD GUI features (screenshots, colors, etc.)

Testing Status

Embedded mode is tested in the CI pipeline with unit tests that mock FreeCAD. However, full integration testing with actual FreeCAD is limited compared to the xmlrpc and socket modes which are tested with the FreeCAD AppImage.

Choosing a Mode

graph TD
    A[Need FreeCAD Robust MCP?] --> B{Platform?}
    B -->|macOS/Windows| C[Use xmlrpc or socket]
    B -->|Linux| D{Need GUI features?}
    D -->|Yes| C
    D -->|No| E{Need fastest execution?}
    E -->|Yes| F[Consider embedded]
    E -->|No| C

Recommendations

Use Case Recommended Mode
General development xmlrpc
Interactive modeling with GUI xmlrpc
CI/CD pipelines on Linux embedded
Docker Desktop containers xmlrpc
Docker Engine on Linux Run server on host
Remote FreeCAD instance Not supported
Debugging connection issues socket

Headless vs GUI Mode

Independent of connection mode, FreeCAD itself can run in GUI or headless mode:

Feature Headless GUI
Object creation Yes Yes
Boolean operations Yes Yes
Export (STEP, STL, etc.) Yes Yes
Screenshots No Yes
Object colors/visibility No Yes
Camera control No Yes

Starting FreeCAD

GUI Mode:

# Using workbench - just start FreeCAD and click "Start Bridge"
just freecad::run-gui  # From source

Headless Mode:

FreeCADCmd /path/to/blocking_bridge.py
just freecad::run-headless  # From source

Troubleshooting

Connection Refused

Error: Connection refused on localhost:9875

Solution: Ensure FreeCAD is running with the Robust MCP Bridge started. Check the bridge status in FreeCAD's toolbar.

Embedded Mode Crash on macOS

SIGSEGV: Segmentation fault

Solution: Embedded mode doesn't work on macOS. Switch to xmlrpc or socket mode.

Timeout Errors

Error: Execution timed out after 30000ms

Solution: Increase the default with FREECAD_TIMEOUT_MS=60000, pass a per-call timeout_ms to execute_python, or optimize the operation. Per-call values take precedence over the environment setting in every connection mode.

A timeout cancels work that is still queued, but it cannot safely interrupt Python code that has already started in FreeCAD. The error reports when code may still be running. Check document state before retrying a state-changing call.

Next Steps