MCP+

MCP+ lets AI assistants (Claude Code and other MCP clients) work in your live FreeCAD session: build and inspect models, run Python, drive the GUI the way a user would, and review CAM jobs. It works with FreeCAD 1.1 and newer development builds.

MCP+ is built on spkane's MCP+ server and adds:

• CAM tools: path statistics, A/B comparisons between two code trees, geometry finders, test fixtures, posting and G-code diffs, gouge and coverage checks, headless test runs, demo recording.

• GuiDriver: run toolbar commands, fill in task panels, answer modal dialogs by rule (see GuiDriver).

• Runs that outlast their timeout keep going: the answer carries a job_token, and get_output_page reads the rest of the output and the result page by page (after CREATeNG/freecad-mcp-bridge).

• bridge_status: what FreeCAD is busy with, or which modal dialog is blocking it, answered even while every other call would wait (after neka-nat/freecad-mcp).

• execute_python_file: run a script with __file__ set and __name__ == "__main__".

• Safer bridge: every request must carry a per-user token, and requests from foreign web pages are refused (see Security and your data).

• Fixes: Addon Manager crash on install, Qt imports through FreeCAD's PySide wrapper, PartDesign/Sketcher tools on FreeCAD 1.x, screenshots, .env handling.

Install it with FreeCAD's Addon Manager or with git (see Installation). The MCP server comes with the add-on; your AI client runs it from the add-on folder with uv.

Platforms. MCP+ runs on Linux, Windows and macOS. The exceptions are the tools that move a real mouse and keyboard: cam_record_demo and GuiDriver's xmouse / xkeys_external helpers use X11 (XTest) and work only on Linux with X11. The other GuiDriver tools work everywhere.

The rest of this README is adapted from the original server's documentation.

Security and your data

What MCP+ allows. MCP+ lets an AI assistant run any Python code in your FreeCAD session, with your user's permissions, the same as a macro you run yourself. There is no sandbox: the code can read and write your files, start programs and reach the network. Your MCP client is the guardrail: use one you trust, and have it ask for your approval before it runs tool calls.

Who can reach the bridge. The bridge only runs while you start it (auto-start is off unless you turn it on in Edit → Preferences → MCP+). It listens on localhost (ports 9875 and 9876 by default), so other computers can't reach it. Every request must also carry a token:

• On its first start the bridge creates a random token in a file only your user can read: ~/.config/mcp-plus/token on Linux, ~/Library/Application Support/mcp-plus/token on macOS, %APPDATA%\mcp-plus\token on Windows. The MCP server reads the same file, so nothing needs configuring, while other users' programs on the same computer can't get in.

• Edit → Preferences → MCP+ → Security shows the token file, copies the token, or replaces it (takes effect at once). Turning the token off is possible for localhost only, and not recommended.

• Requests sent by web pages in your browser (an Origin other than localhost) are refused.

• To use FreeCAD from another computer, prefer an ssh tunnel to its port. If you do set Listen on to another address, the MCP server there needs the token in FREECAD_AUTH_TOKEN; the bridge never listens beyond localhost without one.

Where your data goes. The add-on and the MCP server collect nothing and send nothing to anyone; there is no telemetry. But whatever the assistant asks FreeCAD for becomes part of its conversation: object names and properties, file names and paths, geometry, the output of code it runs, and screenshots of your 3D view. Your MCP client sends that to your AI provider, under that provider's terms. Don't use MCP+ on designs you aren't allowed to share with your AI provider. Code the assistant runs can also reach the network, as any macro can.

Reporting a security problem. Please use GitHub's private vulnerability reporting (the repository's Security tab) rather than a public issue.

Related MCP server: FreeCAD MCP

Table of Contents

• MCP+

  • Security and your data

  • Table of Contents

  • Features

  • Installation Requirements / Dependencies

  • For Users

    • Quick Links

  • MCP+ Server

    • Installation

      • Addon Manager (recommended)

      • Git

      • Finding the add-on folder

    • Configuration

      • MCP Client Configuration

      • Environment Variables

      • Connection Modes

    • Usage

      • Starting the MCP Bridge in FreeCAD

      • Updating

      • Uninstalling

    • Available Tools

      • Execution & Debugging (8 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)

      • CAM review and testing (11 tools)

      • GUI health (2 tools)

      • GuiDriver - drive the GUI like a user (6 tools)

  • For Developers

  • MCP+ Server Development

    • Prerequisites

    • Initial Setup

    • Running Tests

    • Code Quality

  • Architecture

  • Acknowledgements

    • Related Projects

  • License

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 1.1 or newer

• uv, which runs the MCP server and sets up its Python environment on first start

For Users

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

Quick Links

MCP+ Server

Installation

MCP+ is one download: the FreeCAD add-on and the MCP server live in the same folder, freecad-mcp-plus inside FreeCAD's Mod folder. Install it one of two ways.

Addon Manager (recommended)

1. Edit → Preferences → Addon Manager → Custom repositories → +, add https://github.com/Connor9220/freecad-mcp-plus with branch main.

2. Tools → Addon Manager, search for "MCP+", install it and restart FreeCAD.

Git

Clone the repository into FreeCAD's Mod folder and restart FreeCAD:

git clone https://github.com/Connor9220/freecad-mcp-plus.git <Mod folder>/freecad-mcp-plus

Finding the add-on folder

Your MCP client needs the add-on folder's path. Run this in FreeCAD's Python console:

import os; print(os.path.join(App.getUserAppDataDir(), "Mod", "freecad-mcp-plus"))

On Linux with FreeCAD 1.1 this is usually ~/.local/share/FreeCAD/v1-1/Mod/freecad-mcp-plus.

Configuration

MCP Client Configuration

Add something like the following to your MCP client settings, with --project pointing at the add-on folder. For Claude Code, this is ~/.claude.json (or claude mcp add) or a project .mcp.json file:

{
  "mcpServers": {
    "freecad": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/FreeCAD/Mod/freecad-mcp-plus", "freecad-mcp"],
      "env": {
        "FREECAD_MODE": "xmlrpc"
      }
    }
  }
}

Environment Variables

Set these in the env block above.

Connection Modes

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.

Usage

Starting the MCP Bridge in FreeCAD

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

1. Switch to the MCP+ workbench.

2. Click the Start MCP Bridge button in the toolbar, or use the menu MCP Bridge -> Start Bridge. To start it with FreeCAD every time, turn on auto-start in Edit → Preferences → MCP+.

3. You should see in the FreeCAD console:

   MCP Bridge started!
     - XML-RPC: localhost:9875
     - Socket: localhost:9876

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

Updating

• Addon Manager: Tools → Addon Manager → Check for updates, then update MCP+.

• Git: run git pull in the add-on folder.

Restart FreeCAD and your MCP client afterwards.

Uninstalling

• Addon Manager: Tools → Addon Manager, select MCP+, click Uninstall, restart FreeCAD.

• Git: delete the freecad-mcp-plus folder from FreeCAD's Mod folder and restart FreeCAD.

Remove the freecad entry from your MCP client settings as well.

Available Tools

The 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 (8 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)

CAM review and testing (11 tools)

Tools for reviewing and testing CAM (Path) changes. "Local" tools run on the machine of the MCP server (headless FreeCADCmd, file comparisons) and don't need the bridge.

GUI health (2 tools)

GuiDriver - drive the GUI like a user (6 tools)

The add-on ships guidriver (in freecad/MCPPlus/guidriver/, importable inside FreeCAD as freecad.MCPPlus.guidriver; CAM parts in guidriver.cam). It runs real GUI commands, reads and sets task panel widgets through their own Qt API (GUI gating included), presses the task view's OK/Cancel and answers modal dialogs by rule; a dialog no rule matches is rejected after 3 s and reported. See its README. These six tools work on every platform; only the real mouse/keyboard helpers (xmouse, xkeys_external) need Linux with X11.

For Developers

This section covers development setup, contributing, and working with the codebase.

MCP+ Server Development

Prerequisites

• uv

• FreeCAD 1.1 or newer

Initial Setup

Clone the repository into FreeCAD's Mod folder (see Finding the add-on folder), so FreeCAD loads the add-on from your working copy, then install the development tools:

git clone https://github.com/Connor9220/freecad-mcp-plus.git <Mod folder>/freecad-mcp-plus
cd <Mod folder>/freecad-mcp-plus
uv sync --extra dev
uv run pre-commit install

Point your MCP client at the clone as in MCP Client Configuration.

Running Tests

# Unit tests (no FreeCAD required)
uv run pytest tests/unit -o addopts=""

# Integration tests (requires FreeCAD running with the bridge started)
uv run pytest tests/integration -o addopts=""

Code Quality

The project uses strict code quality checks via pre-commit:

• Ruff - Linting and formatting

• MyPy - Type checking

• Bandit - Security scanning

• Codespell - Spell checking

• Secrets scanning - Gitleaks, detect-secrets, TruffleHog

uv run ruff check freecad src             # Lint
uv run mypy src                           # Type check
uv run pre-commit run --all-files         # All hooks

Architecture

See the detailed architecture document for design documentation covering:

• Module structure

• Bridge communication protocols

• Tool registration patterns

• FreeCAD plugin architecture

Acknowledgements

MCP+ is a copy of spkane/freecad-addon-robust-mcp-server by Sean P. Kane, extended by Billy Huddleston. It also takes ideas from neka-nat/freecad-mcp (bridge status, version check) and CREATeNG/freecad-mcp-bridge (paged output for long runs, Origin check, running files). All three are MIT licensed; their notices are in LICENSE.

spkane's original acknowledgements:

This project was developed after analyzing several existing FreeCAD MCP implementations. We are grateful to these projects for their pioneering work and the ideas they contributed to the FreeCAD + AI ecosystem:

Related Projects

• neka-nat/freecad-mcp (MIT License) - The queue-based thread safety pattern and XML-RPC protocol design (port 9875) were directly inspired by this project. Our implementation maintains protocol compatibility while being a complete rewrite with additional features.

• jango-blockchained/mcp-freecad - Inspired our connection recovery mechanisms and multi-mode architecture approach.

• contextform/freecad-mcp - Informed our comprehensive PartDesign and Part workbench tool coverage.

• ATOI-Ming/FreeCAD-MCP - Inspired our macro development toolkit including templates, validation, and automatic imports.

• bonninr/freecad_mcp - Influenced our simple socket-based communication approach.

See docs/COMPARISON.md for a detailed analysis of these implementations and the design decisions they informed.

License

MIT License - see LICENSE for details.