Freecad Addon Robust MCP Server

FreeCAD Robust MCP Server

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
  • Table of Contents
  • Features
  • Installation Requirements / Dependencies
  • For Users
    • Quick Links
  • Robust MCP Server
    • Installation
      • Using pip
      • Using mise and just (from source)
      • Using Docker
    • Configuration
      • Environment Variables
      • Connection Modes
      • MCP Client Configuration
    • Usage
      • Starting the MCP Bridge in FreeCAD
        • Option A: Using the Workbench (Recommended)
        • Option B: Using just commands (from source)
      • Uninstalling the MCP Bridge
        • Checking for Legacy Components
        • Manual Cleanup (if needed)
      • Running Modes
        • XML-RPC Mode (Recommended)
        • Socket Mode (JSON-RPC)
        • Headless Mode
        • Embedded Mode (Linux Only)
    • Available Tools
      • Execution & Debugging (5 tools)
      • Document Management (7 tools)
      • Object Creation - Primitives (8 tools)
      • Object Management (12 tools)
      • PartDesign - Sketching (14 tools)
      • PartDesign - Patterns & Edges (5 tools)
      • View & Display (11 tools)
      • Undo/Redo (3 tools)
      • Export/Import (7 tools)
      • Macro Management (6 tools)
      • Parts Library (2 tools)
  • For Developers
  • Robust MCP Server Development
    • Prerequisites
    • Initial Setup
    • MCP Client Configuration (Development)
    • Development Workflow
    • Running FreeCAD with the MCP Bridge
      • GUI Mode (recommended for development)
      • Headless Mode (for automation/CI)
    • Running Tests
    • Code Quality
  • Architecture
  • Acknowledgements
    • Related Projects
  • 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

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

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)

The containerized Robust MCP Server only supports xmlrpc and socket modes because FreeCAD runs on the host. This topology currently works only with Docker Desktop, whose host.docker.internal forwarding can reach a host-loopback listener.

The container also needs the existing bridge pairing credential; pairing the host account does not provision it in the container. A portable secure provisioning procedure has not yet been validated, so run the MCP server on the host unless the container credential is already provisioned securely.

Security and Linux limitation: The FreeCAD bridge listens on loopback and requires pairing before accepting Python execution. Docker Engine on Linux maps host.docker.internal or host-gateway to a bridge-network address, which cannot reach that loopback listener. Run the MCP server directly on the Linux host instead. Do not expose ports 9875 or 9876 by rebinding the bridge to 0.0.0.0; protected remote transport is not implemented yet.

Configuration

Environment Variables

Connection Modes