Robust MCP Bridge Workbench¶

The Robust MCP Bridge Workbench is a FreeCAD addon that provides the server-side connection point for the Robust MCP Server. It runs inside FreeCAD and exposes XML-RPC and JSON-RPC interfaces.

Overview¶

The workbench provides:

Toolbar controls for starting/stopping the MCP bridge
Status indicator showing connection state
XML-RPC server on port 9875 (default)
JSON-RPC socket server on port 9876 (default)
Headless mode support for automation and CI/CD

Installation¶

The workbench is not yet in the public FreeCAD Addon Manager catalog. Follow the installation guide to install the compatible 0.7.0 or later server and workbench releases, or use both components from the same source checkout for development. The source installer creates Mod/RobustMCPBridge/freecad/RobustMCPBridge/ inside the selected FreeCAD user profile. Release archives instead include their own versioned package directory; follow the guide when using a compatible archive.

GUI Mode Usage¶

Starting the Bridge¶

Switch to the MCP Bridge workbench in FreeCAD
Click Start Bridge in the toolbar
The status indicator turns green when running

You'll see a confirmation message:

MCP Bridge started!
  - XML-RPC: localhost:9875
  - Socket: localhost:9876

Stopping the Bridge¶

Click Stop Bridge in the toolbar. The status indicator turns red.

Status Indicator¶

Hover over the status indicator to see the installed bridge version and its current status.

Color	Status
Green	Bridge running, accepting connections
Red	Bridge stopped
Yellow	Bridge starting/stopping

Headless Mode Usage¶

The workbench includes a blocking bridge script for running in server mode (keeps FreeCAD running).

Starting Headless Mode¶

Linux:

# Use FreeCADCmd instead if that is the executable installed on your system.
freecadcmd ~/.local/share/FreeCAD/v1-1/Mod/RobustMCPBridge/freecad/RobustMCPBridge/freecad_mcp_bridge/blocking_bridge.py

macOS:

/Applications/FreeCAD.app/Contents/Resources/bin/freecadcmd \
    ~/Library/Application\ Support/FreeCAD/v1-1/Mod/RobustMCPBridge/freecad/RobustMCPBridge/freecad_mcp_bridge/blocking_bridge.py

Using just commands (from source):

just freecad::run-headless

The paths above are FreeCAD 1.1 examples for a source installation. Use the active FreeCAD profile’s Mod directory; in FreeCAD’s Python console, print App.getUserAppDataDir() to find its user data directory. For a release archive, use its extracted package directory instead of RobustMCPBridge.

Headless Output¶

FreeCAD version: 1.0.0
============================================================
MCP Bridge started in headless mode!
  - XML-RPC: localhost:9875
  - Socket: localhost:9876

Note: Screenshot and view features are not available in headless mode.
Press Ctrl+C to stop.
============================================================

Features Available by Mode¶

Feature	GUI Mode	Headless Mode
Object creation	Yes	Yes
Boolean operations	Yes	Yes
Export (STEP, STL, etc.)	Yes	Yes
Macro execution	Yes	Yes
Document management	Yes	Yes
Screenshots	Yes	No
Object colors	Yes	No
Object visibility	Yes	No
Camera/view control	Yes	No
Interactive selection	Yes	No

GUI-Only Features

When a GUI-only feature is requested in headless mode, the Robust MCP Server returns a structured error response instead of crashing: {"success": false, "error": "GUI not available - screenshots cannot be captured in headless mode"}

Configuration¶

Workbench Preferences (FreeCAD Side)¶

The workbench has its own preferences that control how the bridge runs inside FreeCAD. Access them via:

Edit → Preferences → Robust MCP Bridge (in FreeCAD's main Preferences dialog)
Robust MCP Bridge → MCP Bridge Preferences... (from the workbench menu)

Setting	Description	Default
Auto-start bridge (GUI)	Start the bridge when the FreeCAD GUI launches	Disabled
Auto-start in console FreeCAD	Start the bridge in long-running console sessions	Disabled
Also auto-start in batch runs	Allow console auto-start for scripts and commands	Disabled
Show status indicator	Display status in FreeCAD's status bar	Enabled
XML-RPC Port	Port for XML-RPC connections	9875
Socket Port	Port for JSON-RPC socket connections	9876

Console and GUI auto-start are independent. Batch auto-start additionally requires console auto-start, and can cause short-lived jobs to compete for the same ports. Unknown command-line options are treated as batch invocations. Pair the bridge before enabling either auto-start option; see Configuration.

Port Configuration

If you change the ports in the workbench preferences while the bridge is running, it will automatically restart with the new configuration.

MCP Server Configuration (Client Side)¶

The external Robust MCP Server (used by Claude Code, etc.) is configured separately using environment variables. These must match the workbench ports:

Environment Variable	Description	Default
`FREECAD_MODE`	Connection mode: `xmlrpc`, `socket`, `embedded`	`xmlrpc`
`FREECAD_XMLRPC_PORT`	XML-RPC server port	9875
`FREECAD_SOCKET_PORT`	JSON-RPC socket server port	9876
`FREECAD_SOCKET_HOST`	Socket/XML-RPC server hostname	`localhost`

Example MCP client configuration with custom ports:

{
  "mcpServers": {
    "freecad": {
      "command": "freecad-mcp",
      "env": {
        "FREECAD_MODE": "xmlrpc",
        "FREECAD_XMLRPC_PORT": "9877"
      }
    }
  }
}

Choosing a Connection Mode

xmlrpc (recommended): Most reliable, works on all platforms. Connects to FreeCAD via XML-RPC protocol.
socket: Alternative protocol using JSON-RPC over TCP sockets. Also works on all platforms.
embedded: Direct Python import of FreeCAD (Linux only). Does not require the workbench but crashes on macOS due to library linking issues. Not recommended for production use.

Port Matching Required

The ports configured in the MCP Server (via environment variables) must match the ports configured in the FreeCAD workbench preferences. If they don't match, the server won't be able to connect to FreeCAD.

Architecture¶

┌─────────────────────────────────────────────────────────────┐
│                    FreeCAD (GUI or Headless)                │
│  ┌───────────────────────────────────────────────────────┐  │
│  │           Robust MCP Bridge Workbench/Plugin          │  │
│  │  ┌─────────────────┐  ┌─────────────────┐             │  │
│  │  │ XML-RPC Server  │  │ Socket Server   │             │  │
│  │  │   (port 9875)   │  │   (port 9876)   │             │  │
│  │  └────────┬────────┘  └────────┬────────┘             │  │
│  │           │                    │                       │  │
│  │           └────────┬───────────┘                       │  │
│  │                    │                                   │  │
│  │           ┌────────▼────────┐                          │  │
│  │           │ FreecadMCPPlugin│                          │  │
│  │           │ (Thread-safe    │                          │  │
│  │           │  queue system)  │                          │  │
│  │           └────────┬────────┘                          │  │
│  │                    │                                   │  │
│  │           ┌────────▼────────┐                          │  │
│  │           │ FreeCAD Python  │                          │  │
│  │           │     Console     │                          │  │
│  │           └─────────────────┘                          │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                           ▲
                           │ Network (localhost)
                           ▼
┌─────────────────────────────────────────────────────────────┐
│           FreeCAD Robust MCP Server (External Process)      │
└─────────────────────────────────────────────────────────────┘

The workbench uses a queue-based thread safety system to ensure FreeCAD operations run on the main GUI thread, preventing crashes from thread-unsafe operations. It selects the PySide binding that matches FreeCAD's active Qt major version. When the host version cannot be detected, it prefers PySide6 and falls back to PySide2. It never falls back across a known Qt major version because Qt 5 and Qt 6 cannot safely share a process. If a GUI session cannot load its matching Qt binding, the bridge refuses to start instead of moving GUI work to a background thread. Genuine headless sessions continue to use the background queue processor.

Troubleshooting¶

Bridge Won't Start¶

Problem: Clicking "Start Bridge" does nothing or shows an error.

Solution:

Check the FreeCAD Python console for error messages
Ensure no other process is using ports 9875/9876
Try restarting FreeCAD

If the console reports that FreeCAD's matching PySide binding could not be loaded, verify that the FreeCAD installation includes its expected Qt binding. This is a FreeCAD runtime problem; do not install PySide separately with pip, because its Qt and Python ABI may not match FreeCAD.

Connection Refused from Robust MCP Server¶

Problem: Robust MCP Server reports "Connection refused"

Solution:

Verify the bridge is running (green status indicator)
Check that ports match between workbench and Robust MCP Server config
On Docker Desktop, verify that FREECAD_SOCKET_HOST is set to host.docker.internal
On Docker Engine for Linux, run the MCP server directly on the host; its container gateway cannot reach the bridge's loopback-only listener

Do not rebind the bridge to 0.0.0.0 to resolve this error. The bridge accepts unauthenticated Python execution, so non-loopback access is unsafe until protected remote transport is implemented.

Headless Mode Hangs¶

Problem: FreeCADCmd with headless server never outputs anything

Solution:

Ensure you're using FreeCADCmd (not freecad)
Check the script path is correct
Try running with -c "print('test')" first to verify FreeCAD works

Macro Tools¶

The MCP server provides tools for working with FreeCAD macros. See Macros for details on using macro tools.