freecad-robust-mcp-fc111/docs/guide/connection-modes.md

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

---

XML-RPC Mode (Recommended)

XML-RPC mode is the default and recommended connection method. It works on all platforms and provides robust, reliable communication.

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)

!!! danger "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.

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 containers	xmlrpc
Remote FreeCAD instance	xmlrpc
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 timeout with FREECAD_TIMEOUT_MS=60000 or optimize your operation.

---

Next Steps

• Tools Reference - Complete API for all 82+ tools
• MCP Resources - Query FreeCAD state via MCP resources