Robust MCP Bridge Workbench/fr

Description

The Robust MCP Bridge Workbench is the server-side connection point that bridges to the Robust MCP Server, which enables external applications to control FreeCAD through the Model Context Protocol (MCP). The workbench runs inside FreeCAD and exposes XML-RPC and JSON-RPC interfaces that external MCP clients can connect to.

This workbench is designed to work with the Robust MCP Server (available on PyPI), which allows AI assistants like Claude to interact with FreeCAD through natural language. The full documentation and source code can be found at github/spkane/freecad-robust-mcp-and-more, where you will find the MCP Server, Bridge and some FreeCAD Macros used for various things, not necessarily related to AI or the MCP work.

Key Features:

Toolbar controls for starting/stopping the MCP bridge.
Status indicator showing connection state (green=running, red=stopped).
XML-RPC server on configurable port (default: 9875).
JSON-RPC socket server on configurable port (default: 9876).
Headless mode support for automation and CI/CD pipelines.
Thread-safe queue system ensuring safe FreeCAD operations.
Configurable auto-start on FreeCAD launch.

Installation

Via Addon Manager (recommended)

Open FreeCAD
Go to Tools → Addon Manager
Search for "Robust MCP Bridge"
Click Install
Restart FreeCAD

Manual installation

Download the latest release from GitHub Releases and extract to your FreeCAD Mod directory:

Linux: ~/.local/share/FreeCAD/Mod/FreecadRobustMCPBridge/
macOS: ~/Library/Application Support/FreeCAD/Mod/FreecadRobustMCPBridge/
Windows: %APPDATA%/FreeCAD/Mod/FreecadRobustMCPBridge/

Usage

GUI mode

Switch to the Robust MCP Bridge workbench using the workbench selector
Click Start Bridge in the toolbar
The status indicator turns green when running
External MCP clients can now connect to localhost:9875 (XML-RPC) or localhost:9876 (Socket)

To stop the bridge, click Stop Bridge in the toolbar.

Headless mode

For automation and CI/CD pipelines, the bridge can run without the GUI:

Linux:

freecadcmd ~/.local/share/FreeCAD/Mod/FreecadRobustMCPBridge/freecad_mcp_bridge/blocking_bridge.py

macOS:

/Applications/FreeCAD.app/Contents/Resources/bin/freecadcmd \
    ~/Library/Application\ Support/FreeCAD/Mod/FreecadRobustMCPBridge/freecad_mcp_bridge/blocking_bridge.py

The bridge will start and keep FreeCAD running until you press Ctrl+C.

Configuration

Access preferences via Edit → Preferences → Robust MCP Bridge or Robust MCP Bridge → MCP Bridge Preferences...

Setting	Description	Default
Auto-start bridge	Start bridge automatically when FreeCAD launches	Disabled
Show status indicator	Display connection 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

Features by mode

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

Connecting MCP clients

This workbench provides the server that MCP clients connect to. To use with AI assistants like Claude, you need an MCP client such as the Robust MCP Server:

pip install freecad-robust-mcp

Or using uv:

uv tool install freecad-robust-mcp

See the GitHub repository for full documentation on configuring MCP clients.

Troubleshooting

Bridge won't start

Check the FreeCAD Python console (View → Panels → Python console) for error messages.
Ensure no other process is using ports 9875/9876.
Try restarting FreeCAD.

Connection refused

Verify the bridge is running (green status indicator in toolbar).
Check that ports match between the workbench preferences and your MCP client configuration.
If connecting from Docker, use host.docker.internal instead of localhost.

Headless mode won't start

Ensure you're using freecadcmd (not freecad).
Verify the script path is correct for your installation.
Test FreeCAD first: freecadcmd -c "print('test')".

Links

Full Documentation - Complete guides, API reference, and tutorials.
GitHub Repository - Source code and issue tracker.
Robust MCP Server on PyPI - The MCP client that connects to this bridge.
Model Context Protocol - The protocol specification.