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.
- FreeCAD Robust MCP Server
- Table of Contents
- Features
- Performance
- Installation Requirements / Dependencies
- For Users
- Robust MCP Server
- Installation
- Configuration
- Usage
- 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
- Architecture
- Acknowledgements
- License
The macros that were originally in this repo under the
/macrosdirectory have been permanently moved to two new GitHub repos:
FreeCAD Forum: addon discussion post
- 150+ MCP Tools: Comprehensive CAD operations including primitives, PartDesign, booleans, export
- Multiple Connection Modes: AUTO mode (socket-first), XML-RPC, 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
This fork includes latency fixes for the FreeCAD ↔ MCP bridge. The public API and the XML-RPC wire protocol are unchanged, so it remains drop-in compatible with existing clients.
Every tool call is a single round trip, and FreeCAD work can only run on the GUI main thread. Previously the bridge drained its request queue on a timer that fired every 50 ms, so each call waited about 25 ms on average for the timer before anything ran. Across a session of many small operations, that fixed overhead dominated and made the bridge feel slow.
The patch addresses this in three ways:
- Event-driven queue draining (main fix): enqueuing a request now wakes the GUI main thread immediately via a thread-safe
QCoreApplication.postEventnotifier instead of waiting for the next timer tick. The timer is kept only as a 250 ms safety net, and headless mode blocks on the queue rather than sleep-polling. - HTTP keep-alive and a threaded XML-RPC server: calls reuse a single socket instead of opening a new TCP connection each time, and health-check pings no longer serialize behind a slow execute.
- Client-side serialization lock: an
asyncio.Lockguards the reused keep-alive connection so the shared socket is never used by two executor threads at once.
GUI thread-safety is preserved: all code still runs through the single main-thread queue, and only the transport layer became concurrent. In a headless benchmark, the per-operation round trip dropped from the old ~25 ms poll floor to roughly 0.09 ms (about 45× less overhead). Real-world gains scale with how many small operations a session issues.
Note: The bridge that runs inside FreeCAD is part of this change, so after patching you must ensure FreeCAD loads the patched addon (reinstall/update it from the patched source, or point FreeCAD's
Moddirectory at it) and restart FreeCAD. Otherwise the slow version keeps running on the FreeCAD side.
- FreeCAD 0.21+ or 1.0+
- Python 3.11 (required for FreeCAD ABI compatibility)
This section covers installation and usage for end users who want to use the Robust MCP Server with AI assistants.
| Resource | Description |
|---|---|
| Documentation | Full documentation, guides, and API reference |
| Docker Hub | Pre-built Docker images for easy deployment |
| PyPI | Python package for pip installation |
| GitHub Releases | Release archives and changelogs |
Note: The Linux container and PyPI package are both named
freecad-robust-mcpwhich differs slightly from this git repository name.
pip install freecad-robust-mcpgit 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 setupRun 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)Note: The containerized Robust MCP Server only supports xmlrpc and socket modes since FreeCAD runs on your host machine (not in the container). The container connects to FreeCAD via host.docker.internal.
| Variable | Description | Default |
|---|---|---|
FREECAD_MODE |
Connection mode: auto, xmlrpc, socket, or embedded |
auto |
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 |
| 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.
Add something like the following to your MCP client settings. For Claude Code, this is ~/.claude/claude_desktop_config.json or a project .mcp.json file:
{
"mcpServers": {
"freecad": {
"command": "freecad-mcp",
"env": {
"FREECAD_MODE": "xmlrpc"
}
}
}
}If installed from source with mise/uv:
{
"mcpServers": {
"freecad": {
"command": "/path/to/mise/shims/uv",
"args": ["run", "--project", "/path/to/freecad-addon-robust-mcp-server", "freecad-mcp"],
"env": {
"FREECAD_MODE": "xmlrpc"
}
}
}
}If using Docker:
{
"mcpServers": {
"freecad": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"--add-host=host.docker.internal:host-gateway",
"-e", "FREECAD_MODE=xmlrpc",
"-e", "FREECAD_SOCKET_HOST=host.docker.internal",
"spkane/freecad-robust-mcp"
]
}
}
}Docker configuration notes:
--rmremoves the container after it exits-ikeeps stdin open for MCP communication--add-host=host.docker.internal:host-gatewayallows the container to connect to FreeCAD on your host (Linux only; macOS/Windows have this built-in)FREECAD_SOCKET_HOST=host.docker.internaltells the Robust MCP Server to connect to FreeCAD on your host machine
Before your AI assistant can connect, you need to start the MCP bridge inside FreeCAD:
-
Install the Robust MCP Bridge workbench via FreeCAD's Addon Manager:
- Edit -> Preferences -> Addon Manager
- Search for "Robust MCP Bridge"
- Install and restart FreeCAD
-
Start the bridge:
- Switch to the Robust MCP Bridge workbench
- Click the Start MCP Bridge button in the toolbar
- Or use the menu: MCP Bridge -> Start Bridge
-
You should see in the FreeCAD console:
MCP Bridge started! - XML-RPC: localhost:9875 - Socket: localhost:9876
# Start FreeCAD with MCP bridge auto-started
just freecad::run-gui
# Or for headless/automation mode:
just freecad::run-headlessAfter starting the bridge, start/restart your MCP client (Claude Code, etc.) - it will connect automatically
To uninstall the Robust MCP Bridge workbench:
- Open FreeCAD
- Go to Edit -> Preferences -> Addon Manager
- Find "Robust MCP Bridge" in the list
- Click Uninstall
- Restart FreeCAD
If you previously used older versions of this project, you may have legacy components installed. Run this command to check what's installed and get cleanup instructions:
just install::statusRemove any legacy files that may conflict with the workbench:
# macOS - remove legacy plugin and macro
rm -rf ~/Library/Application\ Support/FreeCAD/Mod/MCPBridge/
rm -f ~/Library/Application\ Support/FreeCAD/Macro/StartMCPBridge.FCMacro
# Linux - remove legacy plugin and macro
rm -rf ~/.local/share/FreeCAD/Mod/MCPBridge/
rm -f ~/.local/share/FreeCAD/Macro/StartMCPBridge.FCMacroConnects to a running FreeCAD instance via XML-RPC. Works on all platforms.
FREECAD_MODE=xmlrpc freecad-mcpConnects via JSON-RPC socket. Works on all platforms.
FREECAD_MODE=socket freecad-mcpRun FreeCAD in console mode without GUI. Useful for automation.
# If installed from source:
just freecad::run-headlessNote: Screenshot and view features are not available in headless mode.
Runs FreeCAD in-process. Only works on Linux - crashes on macOS/Windows.
FREECAD_MODE=embedded freecad-mcpThe Robust 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.
| Tool | Description | Mode |
|---|---|---|
execute_python |
Execute arbitrary Python code in FreeCAD's context | 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 Robust MCP Server environment (OS, hostname, instance_id) | All |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
This section covers development setup, contributing, and working with the codebase.
# Clone the repository
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
# Install all tools (Python 3.11, uv, just, pre-commit)
mise trust
mise install
# Set up the development environment
just setupThis installs:
- Python 3.11 - Required for FreeCAD ABI compatibility
- uv - Fast Python package manager
- just - Command runner for development workflows
- pre-commit - Git hooks for code quality
Create a .mcp.json file in the project directory:
{
"mcpServers": {
"freecad": {
"command": "/path/to/mise/shims/uv",
"args": ["run", "--project", "/path/to/freecad-addon-robust-mcp-server", "freecad-mcp"],
"env": {
"FREECAD_MODE": "xmlrpc",
"FREECAD_SOCKET_HOST": "localhost",
"FREECAD_XMLRPC_PORT": "9875",
"PATH": "/path/to/mise/shims:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
}
}
}
}Replace the paths with your actual paths:
| Placeholder | Description | Example |
|---|---|---|
/path/to/mise/shims/uv |
Full path to uv via mise shims | ~/.local/share/mise/shims/uv |
/path/to/freecad-addon-robust-mcp-server |
Project directory | /home/me/dev/freecad-addon-robust-mcp-server |
/path/to/mise/shims |
mise shims directory for PATH | ~/.local/share/mise/shims |
Finding your mise shims path:
mise where uv | sed 's|/installs/.*|/shims|'
# Example: /home/user/.local/share/mise/shims (on Linux) or ~/.local/share/mise/shims (on macOS)Commands are organized into modules. Use just to see top-level commands, or just list-<module> to see module-specific commands.
# Show top-level commands and available modules
just
# Show commands in a specific module
just list-mcp # Robust MCP Server commands
just list-freecad # FreeCAD plugin/macro commands
just list-install # Installation commands
just list-quality # Code quality commands
just list-testing # Test commands
just list-docker # Docker commands
just list-documentation # Documentation commands
just list-dev # Development utilities
# List ALL commands from all modules
just list-all
# Install/update dependencies
just install::mcp-server
# Run all checks (linting, type checking, tests)
just all
# Quality commands
just quality::lint # Run ruff linter
just quality::typecheck # Run mypy type checker
just quality::format # Format code
just quality::check # Run all pre-commit hooks
# Testing commands
just testing::unit # Run unit tests
just testing::cov # Run tests with coverage
just testing::integration # Run integration tests
# Run the Robust MCP Server (or with debug logging)
just mcp::run
just mcp::run-debug
# Docker commands
just docker::build # Build image for local architecture
just docker::build-multi # Build multi-arch image (amd64 + arm64)
just docker::run # Run container# Start FreeCAD with auto-started bridge
just freecad::run-guijust freecad::run-headless# Unit tests only (no FreeCAD required)
just testing::unit
# Unit tests with coverage
just testing::cov
# Integration tests (requires running FreeCAD bridge)
just testing::integration
# Integration tests with automatic FreeCAD startup
just testing::integration-autoThe 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
# Run all pre-commit hooks
just quality::check
# Run security/secrets scans
just quality::security
just quality::secretsSee the detailed architecture document for design documentation covering:
- Module structure
- Bridge communication protocols
- Tool registration patterns
- FreeCAD plugin architecture
This project was developed after analyzing several existing FreeCAD Robust MCP implementations. We are grateful to these projects for their pioneering work and the ideas they contributed to the FreeCAD + AI ecosystem:
-
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.
MIT License - see LICENSE for details.
- Phase 1 / Item 1: Added
automode with socket-first selection and XML-RPC fallback; default mode is nowauto. - Phase 1 / Item 2: Added
batch_executeJSON-RPC method and socket bridge API to execute multiple snippets in one RPC round trip. - Phase 1 / Item 3: Added LRU compile cache (
_compile_cached) for repeated execute snippets in the FreeCAD plugin runtime. - Phase 2 / Item 4: Added native RPC endpoints (
get_server_status,list_documents_native) to bypass generic execute for hot introspection calls. - Phase 2 / Item 5: Added execution
capture_mode(full|none|stdout|stderr) to reduce unnecessary stdout/stderr capture overhead on socket RPC paths. - Phase 2 / Item 6: Added XML-RPC status TTL cache (10s) for stable metadata to avoid repeated version/GUI probes in tight polling loops.
- Phase 3 / Item 7: Added optional
orjsonfast-path serialization for socket client/server with stdlib JSON fallback. - Phase 3 / Item 8: Added adaptive bounded queue draining (
MAX_QUEUE_DRAIN_PER_PASS=100) to improve GUI responsiveness during request bursts. - Phase 3 / Item 9: Switched socket request IDs to monotonic integers and optimized XML-RPC client ping to call native
pinginstead ofexecute.
Environment: local headless Python runtime, plugin execution path (freecad_mcp_bridge/server.py), repeated in-process calls.
| Benchmark | Mean (ms) | p50 (ms) | p95 (ms) |
|---|---|---|---|
execute_none_small (_result_=42, capture_mode=none) |
0.000849 | 0.000718 | 0.001321 |
execute_full_small (_result_=42, capture_mode=full) |
0.002138 | 0.001792 | 0.003274 |
execute_none_medium_cached (10-line snippet, cached compile) |
0.001317 | 0.001069 | 0.001979 |
queue_roundtrip_none (_execute_via_queue, capture_mode=none) |
0.014551 | 0.014575 | 0.015703 |
queue_roundtrip_full (_execute_via_queue, capture_mode=full) |
0.015349 | 0.014855 | 0.016268 |
Key takeaway: disabling output capture (capture_mode=none) is ~2.5x faster than full capture for tiny execute calls in this benchmark setup.
- Prefer deferred recompute for multi-step builds: create/update objects with
recompute=False, then run one finalrecompute_document(). - For lowest latency command execution, use
execute_python(..., capture_mode="none")when logs are not needed. - Use
execute_python_batch(items=...)to bundle multiple snippets into one bridge round trip.