Freecad Addon Robust Mcp Server

FreeCAD Robust MCP Server

[](https://opensource.org/licenses/MIT) [](https://pypi.org/project/freecad-robust-mcp/) [](https://pypi.org/project/freecad-robust-mcp/) [](https://hub.docker.com/r/spkane/freecad-robust-mcp) [](https://spkane.github.io/freecad-addon-robust-mcp-server/)

[](https://github.com/spkane/freecad-addon-robust-mcp-server/actions/workflows/test.yaml) [](https://github.com/spkane/freecad-addon-robust-mcp-server/actions/workflows/docker.yaml) [](https://github.com/spkane/freecad-addon-robust-mcp-server/actions/workflows/pre-commit.yaml) [](https://github.com/spkane/freecad-addon-robust-mcp-server/actions/workflows/codeql.yaml)

An MCP (Model Context Protocol) server that enables integration between AI assistants (Claude, GPT, and other MCP-compatible tools) and FreeCAD, allowing AI-assisted development and debugging of 3D models, macros, and workbenches.

Table of Contents

• [FreeCAD Robust MCP Server](#freecad-robust-mcp-server)
• [Table of Contents](#table-of-contents)
• [Features](#features)
• [Installation Requirements / Dependencies](#installation-requirements--dependencies)
• [For Users](#for-users)
• [Quick Links](#quick-links)
• [Robust MCP Server](#robust-mcp-server)
• [Installation](#installation)
• [Using pip (recommended)](#using-pip-recommended)
• [Using mise and just (from source)](#using-mise-and-just-from-source)
• [Using Docker](#using-docker)
• [Configuration](#configuration)
• [Environment Variables](#environment-variables)
• [Connection Modes](#connection-modes)
• [MCP Client Configuration](#mcp-client-configuration)
• [Usage](#usage)
• [Starting the MCP Bridge in FreeCAD](#starting-the-mcp-bridge-in-freecad)
• [Option A: Using the Workbench (Recommended)](#option-a-using-the-workbench-recommended)
• [Option B: Using just commands (from source)](#option-b-using-just-commands-from-source)
• [Uninstalling the MCP Bridge](#uninstalling-the-mcp-bridge)
• [Checking for Legacy Components](#checking-for-legacy-components)
• [Manual Cleanup (if needed)](#manual-cleanup-if-needed)
• [Running Modes](#running-modes)
• [XML-RPC Mode (Recommended)](#xml-rpc-mode-recommended)
• [Socket Mode (JSON-RPC)](#socket-mode-json-rpc)
• [Headless Mode](#headless-mode)
• [Embedded Mode (Linux Only)](#embedded-mode-linux-only)
• [Available Tools](#available-tools)
• [Execution & Debugging (5 tools)](#execution--debugging-5-tools)
• [Document Management (7 tools)](#document-management-7-tools)
• [Object Creation - Primitives (8 tools)](#object-creation---primitives-8-tools)
• [Object Management (12 tools)](#object-management-12-tools)
• [PartDesign - Sketching (14 tools)](#partdesign---sketching-14-tools)
• [PartDesign - Patterns & Edges (5 tools)](#partdesign---patterns--edges-5-tools)
• [View & Display (11 tools)](#view--display-11-tools)
• [Undo/Redo (3 tools)](#undoredo-3-tools)
• [Export/Import (7 tools)](#exportimport-7-tools)
• [Macro Management (6 tools)](#macro-management-6-tools)
• [Parts Library (2 tools)](#parts-library-2-tools)
• [For Developers](#for-developers)
• [Robust MCP Server Development](#robust-mcp-server-development)
• [Prerequisites](#prerequisites)
• [Initial Setup](#initial-setup)
• [MCP Client Configuration (Development)](#mcp-client-configuration-development)
• [Development Workflow](#development-workflow)
• [Running FreeCAD with the MCP Bridge](#running-freecad-with-the-mcp-bridge)
• [GUI Mode (recommended for development)](#gui-mode-recommended-for-development)
• [Headless Mode (for automation/CI)](#headless-mode-for-automationci)
• [Running Tests](#running-tests)
• [Code Quality](#code-quality)
• [Architecture](#architecture)
• [Acknowledgements](#acknowledgements)
• [Related Projects](#related-projects)
• [License](#license)

> The macros that were originally in this repo under the /macros directory have been permanently moved to two new GitHub repos: > > - spkane/freecad-macro-cut-for-magnets > - spkane/freecad-macro-3d-print-multi-export

FreeCAD Forum: addon discussion post

Features

• 150+ MCP Tools: Comprehensive CAD operations including primitives, PartDesign, booleans, export
• Multiple Connection Modes: XML-RPC (recommended), JSON-RPC socket, or embedded
• GUI & Headless Support: Full modeling in headless mode, plus screenshots/colors in GUI mode
• Macro Development: Create, edit, run, and template FreeCAD macros via MCP

Installation Requirements / Dependencies

• FreeCAD 0.21+ or 1.0+
• Python 3.11 (required for FreeCAD ABI compatibility)

---

For Users

This section covers installation and usage for end users who want to use the Robust MCP Server with AI assistants.

Quick Links

| Resource | Description | | ------------------------------------------------------------------------------------- | --------------------------------------------- | | Documentation | Full documentation, guides, and API reference | | Docker Hub | Pre-built Docker images for easy deployment | | PyPI | Python package for pip installation | | GitHub Releases | Release archives and changelogs |

Robust MCP Server

> Note: The Linux container and PyPI package are both named freecad-robust-mcp which differs slightly from this git repository name.

Installation

Using pip (recommended)

pip install freecad-robust-mcp

Using mise and just (from source)

git clone https://github.com/spkane/freecad-addon-robust-mcp-server.git
cd freecad-addon-robust-mcp-server

# Install mise via the Official mise installer script (if not already installed)
curl https://mise.run | sh

mise trust
mise install
just setup

Using Docker

Run the Robust MCP Server in a container. This is useful for isolated environments or when you don't want to install Python dependencies on your host.

# Pull from Docker Hub (when published)
docker pull spkane/freecad-robust-mcp

# Or build locally
git clone https://github.com/spkane/freecad-addon-robust-mcp-server.git
cd freecad-addon-robust-mcp-server
docker build -t freecad-robust-mcp .

# Or use just commands (if you have mise/just installed)
just docker::build        # Build for local architecture
just docker::build-multi  # Build multi-arch (amd64 + arm64)

Note: The containerized Robust MCP Server only supports xmlrpc and socket modes since FreeCAD runs on your host machine (not in the container). The container connects to FreeCAD via host.docker.internal.

Configuration

Environment Variables

| Variable | Description | Default | | --------------------- | ---------------------------------------------------- | ----------- | | FREECAD_MODE | Connection mode: xmlrpc, socket, or embedded | xmlrpc | | FREECAD_PATH | Path to FreeCAD's lib directory (embedded mode only) | Auto-detect | | FREECAD_SOCKET_HOST | Socket/XML-RPC server hostname | localhost | | FREECAD_SOCKET_PORT | JSON-RPC socket server port | 9876 | | FREECAD_XMLRPC_PORT | XML-RPC server port | 9875 | | FREECAD_TIMEOUT_MS | Execution timeout in ms | 30000 |

Connection Modes

| Mode | Description | Platform Support | | ---------- | ------------------------------------------- | --------------------------------- | | xmlrpc | Connects to FreeCAD via XML-RPC (port 9875) | All platforms (recommended) | | socket | Connects via JSON-RPC socket (port 9876) | All platforms | | embedded | Imports FreeCAD directly into process | Linux only (crashes on macOS) |

Note: Embedded mode crashes on macOS because FreeCAD's FreeCAD.so links to @rpath/libpython3.11.dylib, which conflicts with external Python interpreters. Use xmlrpc or socket mode on macOS and Windows.

MCP Client Configuration

Add something like the following to your MCP client settings. For Claude Code, this is ~/.claude/claude_desktop_config.json or a project .mcp.json file:

{
  "mcpServers": {
    "freecad": {
      "command": "freecad-mcp",
      "env": {
        "FREECAD_MODE": "xmlrpc"
      }
    }
  }
}

If installed from source with mise/uv:

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

If using Docker:

{
  "mcpServers": {
    "freecad": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--add-host=host.docker.internal:host-gateway",
        "-e", "FREECAD_MODE=xmlrpc",
        "-e", "FREECAD_SOCKET_HOST=host.docker.internal",
        "spkane/freecad-robust-mcp"
      ]
    }
  }
}

Docker configuration notes:

• --rm removes the container after it exits
• -i keeps stdin open for MCP communication
• --add-host=host.docker.internal:host-gateway allows the container to connect to FreeCAD on your host (Linux only; macOS/Windows have this built-in)
• FREECAD_SOCKET_HOST=host.docker.internal tells the Robust MCP Server to connect to FreeCAD on your host machine

Usage

Starting the MCP Bridge in FreeCAD

Before your AI assistant can connect, you need to start the MCP bridge inside FreeCAD:

Option A: Using the Workbench (Recommended)

1. Install the Robust MCP Bridge workbench via FreeCAD's Addon Manager:

• Edit -> Preferences -> Addon Manager
• Search for "Robust MCP Bridge"
• Install and restart FreeCAD

1. Start the bridge:

• Switch to the Robust MCP Bridge workbench
• Click the Start MCP Bridge button in the toolbar
• Or use the menu: MCP Bridge -> Start Bridge

1. You should see in the FreeCAD console:

```text MCP Bridge started!

• XML-RPC: localhost:9875
• Socket: localhost:9876

```

Option B: Using just commands (from source)

# Start FreeCAD with MCP bridge auto-started
just freecad::run-gui

# Or for headless/automation mode:
just freecad::run-headless

After starting the bridge, start/restart your MCP client (Claude Code, etc.) - it will connect automatically

Uninstalling the MCP Bridge

To uninstall the Robust MCP Bridge workbench:

1. Open FreeCAD
2. Go to Edit -> Preferences -> Addon Manager
3. Find "Robust MCP Bridge" in the list
4. Click Uninstall
5. Restart FreeCAD

Checking for Legacy Components

If you previously used older versions of this project, you may have legacy components installed. Run this command to check what's installed and get cleanup instructions:

just install::status

Manual Cleanup (if needed)

Remove any legacy files that may conflict with the workbench:

# macOS - remove legacy plugin and macro
rm -rf ~/Library/Application\ Support/FreeCAD/Mod/MCPBridge/
rm -f ~/Library/Application\ Support/FreeCAD/Macro/StartMCPBridge.FCMacro

# Linux - remove legacy plugin and macro
rm -rf ~/.local/share/FreeCAD/Mod/MCPBridge/
rm -f ~/.local/share/FreeCAD/Macro/StartMCPBridge.FCMacro

Running Modes

XML-RPC Mode (Recommended)

Connects to a running FreeCAD instance via XML-RPC. Works on all platforms.

FREECAD_MODE=xmlrpc freecad-mcp

Socket Mode (JSON-RPC)

Connects via JSON-RPC socket. Works on all platforms.

FREECAD_MODE=socket freecad-mcp

Headless Mode

Run FreeCAD in console mode without GUI. Useful for automation.

# If installed from source:
just freecad::run-headless

Note: Screenshot and view features are not available in headless mode.

Embedded Mode (Linux Only)

Runs FreeCAD in-process. Only works on Linux - crashes on macOS/Windows.

FREECAD_MODE=embedded freecad-mcp

Available Tools

The Robust MCP Server provides 150+ tools organized into categories. Tools marked with GUI require FreeCAD to be running in GUI mode; they will return an error in headless mode.

Execution & Debugging (5 tools)

| Tool | Description | Mode | | ---------------------------- | ------------------------------------------------------------- | ---- | | execute_python | Execute arbitrary Python code in FreeCAD's context | All | | get_freecad_version | Get FreeCAD version, build date, and Python version | All | | get_connection_status | Check MCP bridge connection status and latency | All | | get_console_output | Get recent FreeCAD console output (up to N lines) | All | | get_mcp_server_environment | Get Robust MCP Server environment (OS, hostname, instance_id) | All |

Document Management (7 tools)

| Tool | Description | Mode | | --------------------- | ----------------------------------------- | ---- | | list_documents | List all open documents with metadata | All | | get_active_document | Get information about the active document | All | | create_document | Create a new FreeCAD document | All | | open_document | Open an existing .FCStd file | All | | save_document | Save a document to disk | All | | close_document | Close a document (with optional save) | All | | recompute_document | Force recomputation of all objects | All |

Object Creation - Primitives (8 tools)

| Tool | Description | Mode | | ----------------- | -------------------------------------------------- | ---- | | create_object | Create a generic FreeCAD object by type ID | All | | create_box | Create a Part::Box with length, width, height | All | | create_cylinder | Create a Part::Cylinder with radius, height, angle | All | | create_sphere | Create a Part::Sphere with radius | All | | create_cone | Create a Part::Cone with two radii and height | All | | create_torus | Create a Part::Torus (donut) with radii and angles | All | | create_wedge | Create a Part::Wedge (tapered box) | All | | create_helix | Create a Part::Helix curve for sweeps and threads | All |

Object Management (12 tools)

| Tool | Description | Mode | | ------------------- | -------------------------------------------------- | ---- | | list_objects | List all objects in a document | All | | inspect_object | Get detailed object info (properties, shape, etc.) | All | | edit_object | Modify properties of an existing object | All | | delete_object | Delete an object from

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: spkane
• Source: spkane/freecad-addon-robust-mcp-server
• License: MIT
• Homepage: https://spkane.github.io/freecad-addon-robust-mcp-server/

Install and usage instructions live in the source repository linked above.