freecad-robust-mcp-fc111/macros/Start_MCP_Bridge/README-StartMCPBridge.md

Start MCP Bridge - FreeCAD Macro

Version: 1.0.0 FreeCAD Version: 0.21 or later License: MIT

Overview

This FreeCAD macro starts the MCP (Model Context Protocol) bridge server, enabling integration between AI assistants (Claude, GPT, and other MCP-compatible tools) and FreeCAD. Once running, AI assistants can control FreeCAD, create and modify 3D models, execute Python code, and more.

Quick Start

Installation

# From the freecad-mcp project directory
just install-bridge-macro

Usage

1. Start FreeCAD
2. Go to Macro -> Macros...
3. Select StartMCPBridge
4. Click Execute

You should see in the FreeCAD console:

MCP Bridge started!
  - XML-RPC: localhost:9875
  - Socket: localhost:9876

You can now use AI assistants with FreeCAD.

Connecting Your MCP Client

After starting the bridge, configure your MCP client (e.g., Claude Code) with:

{
  "mcpServers": {
    "freecad": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/freecad-mcp", "freecad-mcp"],
      "env": {
        "FREECAD_MODE": "xmlrpc"
      }
    }
  }
}

Connection Modes

The bridge starts two servers:

Port	Protocol	Description
9875	XML-RPC	Primary connection mode (recommended)
9876	JSON-RPC	Alternative socket-based connection

Configure your MCP client's FREECAD_MODE environment variable:

• xmlrpc (default) - Uses port 9875
• socket - Uses port 9876

Alternative: Automatic Startup

Instead of running the macro manually each time, you can:

Option 1: Use just run-gui

just run-gui

This starts FreeCAD with the bridge auto-started.

Option 2: Use just run-headless

just run-headless

This starts FreeCAD in headless/console mode with the bridge running. Useful for automation and CI/CD.

Troubleshooting

Error: "MCP Bridge macro not properly installed"

The macro wasn't installed correctly. Run:

just install-bridge-macro

Error: "Failed to import MCP Bridge module"

The freecad-mcp project path is incorrect or the module isn't installed. Ensure:

1. You installed using just install-bridge-macro from the project directory
2. The project's Python dependencies are installed (uv sync)

Bridge won't start

Check the FreeCAD console for error messages. Common issues:

1. Port already in use - Another instance is running, or another application is using ports 9875/9876
2. Python path issues - The project src directory isn't accessible

MCP client can't connect

1. Ensure the bridge is running (check FreeCAD console)
2. Verify your MCP client configuration
3. Restart your MCP client after configuration changes

Uninstallation

just uninstall-bridge-macro

Technical Details

The macro:

1. Adds the freecad-mcp project source to Python's path
2. Imports and instantiates the FreecadMCPPlugin
3. Starts both XML-RPC and JSON-RPC servers
4. Registers handlers for executing Python code, managing documents, creating objects, etc.

The bridge runs in FreeCAD's main thread using Qt timers for non-blocking operation.

License

MIT License - Free to use, modify, and distribute.