freecad-robust-mcp-fc111/docs/guide/workbench.md

MCP Bridge Workbench

The MCP Bridge Workbench is a FreeCAD addon that provides the server-side connection point for the 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

Via FreeCAD Addon Manager (Recommended)

1. Open FreeCAD
2. Go to Tools > Addon Manager
3. Search for "FreeCAD MCP and More" or "MCP Bridge"
4. Click Install
5. Restart FreeCAD

Manual Installation

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

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

---

GUI Mode Usage

Starting the Bridge

1. Switch to the MCP Bridge workbench in FreeCAD
2. Click Start Bridge in the toolbar
3. 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

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

---

Headless Mode Usage

The workbench includes a headless server script for running without the FreeCAD GUI.

Starting Headless Mode

Linux:

freecadcmd ~/.local/share/FreeCAD/Mod/FreecadRobustMCP/freecad_mcp_bridge/headless_server.py

macOS:

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

Using just commands (from source):

just freecad::run-headless

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

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

---

Configuration

The workbench uses default ports that can be customized in the MCP server configuration:

Server	Default Port	Environment Variable
XML-RPC	9875	FREECAD_XMLRPC_PORT
Socket	9876	FREECAD_SOCKET_PORT

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    FreeCAD (GUI or Headless)                │
│  ┌───────────────────────────────────────────────────────┐  │
│  │              MCP Bridge Workbench/Plugin              │  │
│  │  ┌─────────────────┐  ┌─────────────────┐             │  │
│  │  │ XML-RPC Server  │  │ Socket Server   │             │  │
│  │  │   (port 9875)   │  │   (port 9876)   │             │  │
│  │  └────────┬────────┘  └────────┬────────┘             │  │
│  │           │                    │                       │  │
│  │           └────────┬───────────┘                       │  │
│  │                    │                                   │  │
│  │           ┌────────▼────────┐                          │  │
│  │           │ FreecadMCPPlugin│                          │  │
│  │           │ (Thread-safe    │                          │  │
│  │           │  queue system)  │                          │  │
│  │           └────────┬────────┘                          │  │
│  │                    │                                   │  │
│  │           ┌────────▼────────┐                          │  │
│  │           │ FreeCAD Python  │                          │  │
│  │           │     Console     │                          │  │
│  │           └─────────────────┘                          │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                           ▲
                           │ Network (localhost)
                           ▼
┌─────────────────────────────────────────────────────────────┐
│              FreeCAD 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.

---

Troubleshooting

Bridge Won't Start

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

Solution:

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

Connection Refused from MCP Server

Problem: MCP server reports "Connection refused"

Solution:

1. Verify the bridge is running (green status indicator)
2. Check that ports match between workbench and MCP server config
3. If using Docker, ensure you're using host.docker.internal as the host

Headless Mode Hangs

Problem: FreeCADCmd with headless server never outputs anything

Solution:

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

---

Included Macros

The addon bundle also includes standalone FreeCAD macros:

• MultiExport - Export objects to multiple formats simultaneously
• CutObjectForMagnets - Cut objects with aligned magnet holes for 3D printing

See Macros for details.