Files

T

e11ba127cd docs: update repository name and add clear acknowledgements section to primary README (#12 )

* docs: Update git repo name

* docs: add acknowledgements section

* docs: clarifications and consistency improvements

* ci: Update CodeRabbit configuration

* Update README.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* docs: Fix repo path everywhere

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

2026-01-05 06:26:06 -08:00

3.2 KiB

Raw Blame History

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

Start FreeCAD
Go to Macro -> Macros...
Select StartMCPBridge
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-robust-mcp-and-more", "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:

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

Bridge won't start

Check the FreeCAD console for error messages. Common issues:

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

MCP client can't connect

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

Uninstallation

just uninstall-bridge-macro

Technical Details

The macro:

Adds the freecad-mcp project source to Python's path
Imports and instantiates the FreecadMCPPlugin
Starts both XML-RPC and JSON-RPC servers
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.

3.2 KiB Raw Blame History