Skip to main content
Glama
FreeCAD MCP Server

FreeCAD MCP Server

by theosib

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

Related MCP server: freecad-mcp

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)

Available Tools

9 tools
analyze_shapeA

Detailed topological analysis of an object's shape.

Returns shape type, volume, area, center of mass, bounding box, topology counts (vertices/edges/faces/solids), face classifications (plane/cylinder/cone/sphere/toroid with parameters), and edge details.

Use this to understand the geometric result of a feature — especially useful for diagnosing why a boolean or pocket operation produced unexpected geometry.

Args: name: Object name that has a Shape (e.g., "Pad001", "Cut001"). doc_name: Document name. Empty string uses the active document.

Inputs: name (required), doc_name.

execute_scriptA

Execute arbitrary Python code in FreeCAD's interpreter context.

The script has access to: FreeCAD, FreeCADGui, App, Gui, doc (active document). Stdout and stderr are captured and returned.

Use this as an escape hatch for operations not covered by the specific tools above. For example: creating objects, modifying properties, running macros, or accessing FreeCAD APIs not yet exposed as tools.

Args: script: Python code to execute.

Inputs: script (required).

get_document_graphA

Get a structured representation of a document's feature tree.

Returns every object with its TypeId, label, properties, dependency links (InList/OutList), validity state, and touch state. This is the primary tool for understanding what a FreeCAD model contains.

Args: doc_name: Document name. Empty string uses the active document.

Inputs: doc_name.

get_screenshotA

Capture the current 3D viewport as a base64-encoded PNG image.

Returns the image as a base64 string along with dimensions. Useful for visual inspection of the model state.

Args: width: Image width in pixels. height: Image height in pixels.

Inputs: width, height.

get_sketch_diagnosticsA

Deep inspection of a sketch's constraint health.

Returns constraint count, geometry count, degrees of freedom, whether the sketch is fully constrained, and a detailed list of every constraint (type, value, referenced geometry indices, driving status, and whether it is redundant or conflicting).

Also returns geometry elements with type-specific details (line endpoints, circle centers/radii, arc parameters).

This is the primary diagnostic tool for sketch problems — over-constrained, under-constrained, or conflicting sketches.

Args: name: Sketch object name (e.g., "Sketch001"). doc_name: Document name. Empty string uses the active document.

Inputs: name (required), doc_name.

inspect_objectA

Get a full property dump and shape analysis for a single FreeCAD object.

Returns all properties (with types, groups, and documentation), dependency info, validity state, and basic shape metadata if the object has geometry.

Args: name: Object name (e.g., "Pad001", "Sketch002"). doc_name: Document name. Empty string uses the active document.

Inputs: name (required), doc_name.

list_documentsA

List all open FreeCAD documents with their names, labels, file paths, object counts, and modification status.

Inputs: no named parameters. Returns: result

reload_handlersA

Hot-reload all FreeCAD addon handler modules.

Call this after editing handler code (in freecad_addon/handlers/) to pick up changes without restarting FreeCAD. Reloads all handler modules and re-registers them with the RPC server.

Inputs: no named parameters.

tracked_recomputeA

Recompute a document and track what changed.

Snapshots every object's validity before recomputing, then diffs against the post-recompute state. Reports:

  • new_errors: objects that were valid before but are now invalid

  • resolved: objects that were invalid but are now valid

  • persistent_errors: objects that remain invalid

  • valid_count: number of objects that stayed valid

Use this instead of raw recompute to understand the impact of changes.

Args: doc_name: Document name. Empty string uses the active document.

Inputs: doc_name.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 9 tools

    Disambiguation4/5

    The tools are largely distinct: document listing, feature-tree inspection, single-object property dumps, shape analysis, sketch diagnostics, recompute tracking, scripting, and screenshots all have clear purposes. Minor overlap exists between inspect_object and analyze_shape, but the descriptions separate basic shape metadata from detailed topological analysis.

    Naming Consistency4/5

    Most tool names follow a clear verb_noun pattern: list_documents, get_document_graph, inspect_object, analyze_shape, execute_script, get_screenshot, reload_handlers. The one notable deviation is tracked_recompute, which reads as an adjective-noun phrase rather than an imperative verb_noun name.

    Tool Count5/5

    Nine tools is a well-scoped set for a FreeCAD server. Each tool covers a meaningful capability, and there is no significant bloat or obvious redundancy in the overall surface.

    Completeness3/5

    The inspection/diagnostic side is thorough, covering documents, feature graphs, object properties, shape topology, sketch constraints, and recompute effects. However, there are no dedicated creation, modification, or deletion tools; execute_script is the only generic escape hatch for those operations, which is a notable first-class coverage gap for a general FreeCAD server.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables control of FreeCAD CAD software from Claude Desktop through natural language commands. Supports creating, editing, and managing 3D objects, executing Python code, and generating screenshots of designs.
      10
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables to control FreeCAD from Claude Desktop through MCP, allowing CAD operations like creating and editing objects, taking screenshots, and executing Python code.
      11
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables Claude Desktop to control FreeCAD for 3D CAD modeling, including creating, editing, and deleting objects, executing Python code, and running FEM analyses.
      14
      MIT