# Connection Modes - FreeCAD Robust MCP Suite
FreeCAD Robust MCP Suite - MCP Server, Bridge Workbench, and Macros for AI assistant integration

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 (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)

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

2026-01-12
2026-01-06