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

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)

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