freecad-mcp-plus
Health Warn
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 5 GitHub stars
Code Pass
- Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Pass
- Permissions — No dangerous permissions requested
No AI report is available for this listing yet.
MCP+ - MCP bridge for AI assistants in FreeCAD, with CAM tools
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, andget_output_pagereads 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
PySidewrapper,
PartDesign/Sketcher tools on FreeCAD 1.x, screenshots,.envhandling.
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. MCP+ shows you the code first and
runs it only when you say so (below); your MCP client's own approval prompts are a second guard.
Approving the AI's code. Before code the AI wrote runs (execute_python, execute_python_file,safe_execute, run_macro, fc_eval, a cam_ab probe, or the python steps ofcam_record_demo), FreeCAD shows it in a dialog. Run it only this time, for the rest of the FreeCAD
session, or always; Cancel (the default button) doesn't run it. Edit → Preferences → MCP+ →
Security → GUI AI Permission shows and changes that choice: Ask every time, Allow for this FreeCAD session, or
Always allow. Documents and files the AI reads can carry instructions planted by someone else, so
read the code before you run it. The other tools (create_box, the CAM tools and so on) run the
add-on's own code and don't ask.
- Headless FreeCAD (FreeCADCmd) has no window to ask in, so it refuses the AI's code (the other tools
still work) unless you set Headless AI Permission to allow it in the same preferences (headless
FreeCAD reads them too). fc_evalandcam_abstart their own FreeCADCmd; they ask in the FreeCAD you have open, and
refuse when none is running.- For unattended setups, set GUI AI Permission to always allow, and Headless AI
Permission for headless FreeCAD.
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 and every answer is signed with a token:
- On its first start the bridge creates a random token in a file only your user can read:
~/.config/mcp-plus/tokenon Linux,~/Library/Application Support/mcp-plus/tokenon macOS,%APPDATA%\mcp-plus\tokenon Windows. The MCP server reads the same file, so nothing needs
configuring, while other users' programs on the same computer can't get in. - The token itself never travels: each request carries an HMAC signature made with it, which can't
be changed or replayed, and the bridge signs its answers the same way. - Edit → Preferences → MCP+ → Security shows the token file, copies the token, or replaces it
(takes effect at once). The token can't be turned off. - Requests sent by web pages in your browser (an
Originother than localhost) are refused. - To use FreeCAD from another computer, the simplest way is to run the MCP server there over ssh
as a stdio server (ssh <host> freecad-mcp), which keeps the bridge on localhost. Otherwise set
Listen on to localhost and one of this computer's addresses, such aslocalhost, 192.168.0.10(leave localhost out to use the address only;0.0.0.0isn't allowed; the first time
another computer connects, FreeCAD asks whether to let it in, for this session or always) and give the MCP server there the token inFREECAD_AUTH_TOKEN. Those connections are encrypted with the token as the key
(TLS-PSK), which needs Python 3.13 or newer on both sides: FreeCAD's own Python and the MCP
server's. On an older FreeCAD the bridge stays on localhost; an ssh tunnel to its port works
everywhere.FREECAD_MCP_TLS=1makes the MCP server use TLS-PSK even tolocalhost(a port
forward to another machine). - The MCP server's own HTTP mode (
FREECAD_TRANSPORT=http) listens on this computer only.
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.
Table of Contents
- MCP+
- Security and your data
- Table of Contents
- Features
- Installation Requirements / Dependencies
- For Users
- MCP+ Server
- Installation
- Configuration
- Usage
- 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
- Architecture
- Acknowledgements
- 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
For Users
This section covers installation and usage for end users who want to use the MCP+ server with AI assistants.
Quick Links
| Resource | Description |
|---|---|
| Documentation | Original server's documentation and API reference |
| GitHub Releases | MCP+ releases and changelogs |
| Issues | Bug reports and feature requests |
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)
- Edit → Preferences → Addon Manager → Custom repositories → +, add
https://github.com/Connor9220/freecad-mcp-pluswith branchmain. - 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.
| 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.
Usage
Starting the MCP Bridge in FreeCAD
Before your AI assistant can connect, you need to start the MCP bridge inside FreeCAD:
Switch to the MCP+ workbench.
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+.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 pullin 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-plusfolder from FreeCAD'sModfolder 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)
| Tool | Description | Mode |
|---|---|---|
execute_python |
Execute arbitrary Python code in FreeCAD's context | All |
execute_python_file |
Run a .py file as __main__, with __file__ set |
All |
get_output_page |
Read a run that outlasted its timeout, page by page | All |
bridge_status |
What FreeCAD is busy with; answers even when FreeCAD is stuck | 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 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 a document | All |
set_placement |
Set object position and rotation | All |
scale_object |
Scale an object uniformly or non-uniformly | All |
rotate_object |
Rotate an object around an axis | All |
copy_object |
Create a copy of an object | All |
mirror_object |
Mirror an object across a plane (XY, XZ, YZ) | All |
boolean_operation |
Fuse, cut, or intersect objects | All |
get_selection |
Get currently selected objects | GUI |
set_selection |
Select specific objects by name | GUI |
clear_selection |
Clear all selections | GUI |
PartDesign - Sketching (14 tools)
| Tool | Description | Mode |
|---|---|---|
create_partdesign_body |
Create a PartDesign::Body container | All |
create_sketch |
Create a sketch on a plane or face | All |
add_sketch_rectangle |
Add a rectangle to a sketch | All |
add_sketch_circle |
Add a circle to a sketch | All |
add_sketch_line |
Add a line (with optional construction flag) | All |
add_sketch_arc |
Add an arc by center, radius, and angles | All |
add_sketch_point |
Add a point (useful for hole centers) | All |
pad_sketch |
Extrude a sketch (additive) | All |
pocket_sketch |
Cut into solid using a sketch (subtractive) | All |
revolution_sketch |
Revolve a sketch around an axis (additive) | All |
groove_sketch |
Revolve a sketch around an axis (subtractive) | All |
create_hole |
Create parametric holes with optional threading | All |
loft_sketches |
Create a loft through multiple sketches | All |
sweep_sketch |
Sweep a profile along a spine path | All |
PartDesign - Patterns & Edges (5 tools)
| Tool | Description | Mode |
|---|---|---|
linear_pattern |
Create linear pattern of a feature | All |
polar_pattern |
Create polar/circular pattern of a feature | All |
mirrored_feature |
Mirror a feature across a plane | All |
fillet_edges |
Add fillets (rounded edges) | All |
chamfer_edges |
Add chamfers (beveled edges) | All |
View & Display (11 tools)
| Tool | Description | Mode |
|---|---|---|
get_screenshot |
Capture a screenshot of the 3D view | GUI |
set_view_angle |
Set camera to standard views (Front, Top, etc.) | GUI |
fit_all |
Zoom to fit all objects in view | GUI |
zoom_in |
Zoom in by a factor | GUI |
zoom_out |
Zoom out by a factor | GUI |
set_camera_position |
Set camera position and look-at point | GUI |
set_object_visibility |
Show/hide objects | GUI |
set_display_mode |
Set display mode (Shaded, Wireframe, etc.) | GUI |
set_object_color |
Set object color as RGB values | GUI |
list_workbenches |
List available FreeCAD workbenches | All |
activate_workbench |
Switch to a different workbench | All |
Undo/Redo (3 tools)
| Tool | Description | Mode |
|---|---|---|
undo |
Undo the last operation | All |
redo |
Redo a previously undone operation | All |
get_undo_redo_status |
Get available undo/redo operations | All |
Export/Import (7 tools)
| Tool | Description | Mode |
|---|---|---|
export_step |
Export to STEP format (ISO CAD exchange) | All |
export_stl |
Export to STL format (3D printing) | All |
export_3mf |
Export to 3MF format (modern 3D printing) | All |
export_obj |
Export to OBJ format (Wavefront) | All |
export_iges |
Export to IGES format (older CAD exchange) | All |
import_step |
Import a STEP file | All |
import_stl |
Import an STL file as mesh | All |
Macro Management (6 tools)
| Tool | Description | Mode |
|---|---|---|
list_macros |
List all available FreeCAD macros | All |
run_macro |
Execute a macro by name | All |
create_macro |
Create a new macro file | All |
read_macro |
Read macro source code | All |
delete_macro |
Delete a user macro | All |
create_macro_from_template |
Create macro from template (basic, part, etc.) | All |
Parts Library (2 tools)
| Tool | Description | Mode |
|---|---|---|
list_parts_library |
List parts in FreeCAD's parts library | All |
insert_part_from_library |
Insert a part from the library | All |
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.
| Tool | Description | Mode |
|---|---|---|
cam_path_stats |
Counts, cut/rapid length, Z levels, link heights, upward feeds of an op | All |
cam_ab |
Run a probe against two git refs of the CAM code and compare the results | Local |
cam_find_geometry |
Find faces and edges by normal, height or radius | All |
cam_fixture |
Build a test Job with stock, tool controller and operation | All |
cam_post |
Post a job; upload, username and remote dialogs are cancelled | All |
cam_gcode_diff |
Compare two G-code outputs | Local |
cam_gouge_check |
Sweep the tool along link moves and report gouges | All |
cam_coverage |
Grid check of the material an operation leaves uncut | All |
cam_tests |
Run CAM unit tests, optionally against a baseline tree | Local |
fc_eval |
Run a script in headless FreeCADCmd and return its real exit code | Local |
cam_record_demo |
Record a captioned GUI demo on an off-screen display | GUI |
GUI health (2 tools)
| Tool | Description | Mode |
|---|---|---|
gui_health |
Open panels, stray dialogs, active document, new Report-view errors | GUI |
gui_reset |
Close stray panels and dialogs; gets in even while a run is stuck on a dialog | GUI |
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.
| Tool | Description | Mode |
|---|---|---|
gui_run_command |
Run a command like a toolbar click, with modal-dialog rules | GUI |
gui_panel |
Dump / set / click / OK / Cancel the open task panel | GUI |
gui_edit |
Open an object's editor like a tree double-click | GUI |
cam_gui_add_base |
Base Geometry "Add" on the open CAM operation panel | GUI |
cam_gui_check |
Pre-post warnings (and summary) for a CAM job | GUI |
cam_gui_post |
Post a job, answering the post's dialogs by rule (never uploads) | GUI |
For Developers
This section covers development setup, contributing, and working with the codebase.
MCP+ Server Development
Prerequisites
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.
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found