Robust MCP Bridge Workbench

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)

1. Open FreeCAD
2. Go to Tools → Addon Manager
3. Search for "Robust MCP Bridge"
4. Click Install
5. 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

1. Switch to the Robust MCP Bridge workbench using the workbench selector
2. Click Start Bridge in the toolbar
3. The status indicator turns green when running
4. 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...

Features by Mode

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

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

Connection refused

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

Headless mode won't start

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

Links

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