Robust MCP Bridge Workbench
Description[edit | edit source]
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[edit | edit source]
Via Addon Manager (recommended)[edit | edit source]
- Open FreeCAD
- Go to Tools → Addon Manager
- Search for "Robust MCP Bridge"
- Click Install
- Restart FreeCAD
Manual installation[edit | edit source]
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[edit | edit source]
GUI mode[edit | edit source]
- 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[edit | edit source]
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[edit | edit source]
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[edit | edit source]
| 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[edit | edit source]
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[edit | edit source]
Bridge won't start[edit | edit source]
- 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[edit | edit source]
- 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.internalinstead oflocalhost.
Headless mode won't start[edit | edit source]
- Ensure you're using
freecadcmd(notfreecad). - Verify the script path is correct for your installation.
- Test FreeCAD first:
freecadcmd -c "print('test')".
Links[edit | edit source]
- 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.

