Jump to content

Robust MCP Bridge Workbench

From FreeCAD Documentation
Robust MCP Bridge Workbench icon

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]

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

Robust MCP Bridge workbench toolbar

  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.

Robust MCP Bridge workbench statusbar

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

Robust MCP Bridge workbench preference pane

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]

  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[edit | edit source]

  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[edit | edit source]

  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[edit | edit source]