FreeCAD MCP Server

An MCP (Model Context Protocol) server that bridges Claude with a live FreeCAD instance. It gives Claude deep access to FreeCAD's runtime state — document structure, object properties, shape topology, sketch constraint health, and more — enabling AI-assisted CAD work and FreeCAD development debugging.

What It Does

Unlike simple script-execution MCP servers, this project provides rich context extraction that lets Claude genuinely understand what's happening inside FreeCAD:

Tool	What It Returns
list_documents	All open documents with names, file paths, object counts
get_document_graph	Full feature tree — every object with TypeId, properties, dependency links, validity state
inspect_object	Complete property dump for a single object, with shape metadata
analyze_shape	Topological analysis — face classifications (Plane/Cylinder/Cone/...), edge details, bounding box, volume
get_sketch_diagnostics	Constraint health — DOF, conflicts, redundancies, every constraint and geometry element with coordinates
tracked_recompute	Recompute with before/after diff — new errors, resolved errors, persistent errors
execute_script	Run arbitrary Python inside FreeCAD (escape hatch for anything not covered above)
get_screenshot	Capture the 3D viewport as a base64 PNG
reload_handlers	Hot-reload handler code without restarting FreeCAD

Architecture

Claude (Code/Desktop)  ←stdio MCP→  Bridge Server  ←TCP:9876→  FreeCAD Addon
                                     (this project)              (inside FreeCAD)

The project has two components:

1. FreeCAD addon (freecad_addon/) — runs inside FreeCAD as a workbench. Starts a threaded TCP server that accepts JSON-RPC requests and executes them on FreeCAD's main thread via a QTimer-polled work queue.

2. MCP bridge server (src/freecad_mcp_agent/) — spawned by Claude via stdio. Connects to the addon over TCP and translates MCP tool calls into JSON-RPC requests.

Installation

1. Install the MCP bridge

# Clone the repo
git clone https://github.com/theosib/FreeCAD-MCP-Server.git
cd FreeCAD-MCP-Server

# Create a venv and install
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

2. Install the FreeCAD addon

FreeCAD doesn't reliably follow symlinks on macOS, so we use a thin loader file.

Find your FreeCAD Mod directory:

• macOS: ~/Library/Application Support/FreeCAD/Mod/ (or ~/Library/Application Support/FreeCAD/v1-2/Mod/ for weekly builds)
• Linux: ~/.local/share/FreeCAD/Mod/
• Windows: %APPDATA%/FreeCAD/Mod/

Tip: Run FreeCAD.getUserAppDataDir() in FreeCAD's Python console to find the exact path.

Create the loader:

mkdir -p "<your-mod-dir>/FreeCADMCPAgent"

Create <your-mod-dir>/FreeCADMCPAgent/InitGui.py with:

import sys
_ADDON_DIR = "/absolute/path/to/FreeCAD-MCP-Server/freecad_addon"
if _ADDON_DIR not in sys.path:
    sys.path.insert(0, _ADDON_DIR)
_project_init = _ADDON_DIR + "/InitGui.py"
_ns = dict(globals())
_ns["__file__"] = _project_init
with open(_project_init) as _f:
    exec(compile(_f.read(), _project_init, "exec"), _ns)

Replace /absolute/path/to/FreeCAD-MCP-Server with the actual path to your clone.

3. Configure Claude Code

Add a .mcp.json to your working directory (or FreeCAD source tree):

{
  "mcpServers": {
    "freecad-debug": {
      "command": "/absolute/path/to/FreeCAD-MCP-Server/.venv/bin/freecad-mcp-agent",
      "env": {
        "FREECAD_MCP_HOST": "127.0.0.1",
        "FREECAD_MCP_PORT": "9876"
      }
    }
  }
}

Usage

1. Start FreeCAD. The RPC server auto-starts on port 9876 (you'll see "MCP Debug Agent: RPC server auto-started" in FreeCAD's console). Set FREECAD_MCP_NO_AUTOSTART=1 to disable auto-start.

2. Launch Claude Code in a directory with the .mcp.json config.

3. Use the tools. Claude can now inspect your FreeCAD model:

"What objects are in the current document?"

"The Pocket001 feature looks wrong — can you diagnose it?"

"Is Sketch003 fully constrained? Are there any conflicts?"

"Recompute the document and tell me what changed."

Use Case: FreeCAD Development Debugging

This project was designed for debugging FreeCAD itself. When the .mcp.json is placed in a FreeCAD source tree, Claude Code gets simultaneous access to:

• Source code — C++ and Python files, git history, build system (via Claude Code's native file access)
• Live runtime state — object properties, shape topology, constraint solver state (via MCP tools)

This lets Claude correlate what the code should do with what the runtime actually produced. See docs/freecad-fork-instructions.md for detailed workflows and a TypeId-to-source-file mapping table.

Environment Variables

Variable	Default	Purpose
FREECAD_MCP_HOST	127.0.0.1	RPC server host
FREECAD_MCP_PORT	9876	RPC server port
FREECAD_MCP_NO_AUTOSTART	(unset)	Set to 1 to disable auto-start of the RPC server

Project Structure

FreeCAD-MCP-Server/
├── pyproject.toml                  # Python package config
├── src/freecad_mcp_agent/
│   ├── server.py                   # MCP server (stdio, all tool definitions)
│   └── bridge.py                   # TCP client connecting to FreeCAD addon
├── freecad_addon/
│   ├── InitGui.py                  # Workbench registration + auto-start
│   ├── mcp_commands.py             # Start/Stop commands, handler registration
│   ├── rpc_server.py               # Threaded TCP server + main-thread dispatch
│   ├── package.xml                 # FreeCAD addon metadata
│   └── handlers/
│       ├── document.py             # list_documents, get_document_graph
│       ├── inspection.py           # inspect_object, analyze_shape
│       ├── sketcher.py             # get_sketch_diagnostics
│       ├── recompute.py            # tracked_recompute
│       ├── execution.py            # execute_script
│       └── viewport.py             # get_screenshot
└── docs/
    └── freecad-fork-instructions.md

License

LGPL-2.1-or-later (same as FreeCAD)