CADPilot
CADPilot is an MCP server that gives AI clients full programmatic control of FreeCAD — creating documents, building parametric models, running Python, managing reviewable modeling sessions, sensing geometry, and assembling parts.
Document management: create, list, and inspect documents and their objects (with optional screenshots).
Unified CAD modeling via
cad(): create/edit/delete objects, batch ops, PartDesign features (pad, pocket, revolution, groove, thickness, draft), sketches and spreadsheet variables, datum planes, hulls, booleans, fillets, chamfers, lofts, sweeps, mirrors, patterns, moves, and appearance/color.Arbitrary Python execution:
execute_codeon the GUI thread, plusexecute_code_async/get_task_resultfor long background OCCT computations.Modeling sessions & journaling: start/pause/resume/list sessions, record steps, roll back and redo, add notes, and save completed workflows as reusable patterns.
Knowledge memory: save and recall modeling patterns, get per-operation docs, and introspect the live FreeCAD API.
Geometry sensing: measure volume/area/bbox/COM/validity, list faces/edges/vertices for selection, get global positioning info, and check interference between objects.
Assembly: auto/explicit anchors, one-shot anchor-based mating with residual checks, spatial audits (floating parts, interferences), and a persistent joint-based assembly session with solve/verify/rollback.
Visual feedback: on-demand screenshots of the active view from standard camera angles, focused on a chosen object.
Provides full control over FreeCAD CAD software, enabling AI agents to create documents, build constrained sketches, run parametric features, assemble parts with persistent joints, and verify geometry.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@CADPilot Create a 100mm cube with a 20mm hole through the center"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
CADPilot
English | Chinese
AI pilots FreeCAD. CADPilot is an MCP (Model Context Protocol) server that gives AI clients (Cherry Studio, Claude Code, ZCode, Kimi Code, Claude Desktop, …) full control of FreeCAD: create documents, build constrained sketches, run parametric features, assemble parts with persistent joints, and verify geometry, all via tool calls over XML-RPC.
Showcase
Models built by the AI through CADPilot (demo files live in examples/):
Backpack | Desk Fan |
Violin | Leaf |
Related MCP server: FreeCAD Robust MCP Server
Features
Parametric modeling, end to end: spreadsheet-driven variables, fully constrained sketches, PartDesign features (pad/pocket/revolution/…), dress-up ops, and a multi-view 2D→3D visual hull, all through one unified
cad()tool.Step journal & review loop: every mutation is also journaled on the FreeCAD side and shown in the Steps panel dock: run planned steps, accept the good ones (soft lock), reject or roll back the rest, edit parameters in place, and replay the whole build from the journal.
execute_codeis a first-class citizen: a snippet that changes the model is wrapped in a transaction and becomes a rollback-able, replayable step, while a read-only inspection never blocks a rollback. Hand edits in the GUI sync back into the recorded steps; session rollback remains for whole-session undo.Persistence: sessions, patterns, and settings survive restarts as JSON under
~/.cadpilot/; pause a session today, resume it tomorrow.Geometry sensing: measure volumes/areas, inspect face/edge topology, and check interference after every step; quantitative feedback replaces guesswork on complex models.
Data-driven assembly: named anchors, residual-checked mates, connectivity audits, and persistent joints (FreeCAD 1.1 Assembly workbench) with declarative priority trimming.
Workflow memory: successful modeling recipes are stored as reusable patterns and recalled on demand; the agent gets better the more you use it.
Built-in troubleshooting: the
diagnosetool probes the RPC port, the FreeCAD process, the addon install and its logs on Windows/macOS/Linux, ends with a concrete fix, and works even while FreeCAD is down or frozen.get_addon_logreads the addon's debug ring buffer even when the GUI is wedged.Token-friendly: text-first responses with screenshots on demand via
get_view(384 px cap, file delivery), a tiny tool surface, and on-demand operation docs keep context usage low.
Installation
Step 1: Install the FreeCAD addon
FreeCAD addon directory:
Windows:
FreeCAD 1.1:
%APPDATA%\FreeCAD\v1-1\Mod\FreeCAD 1.0:
%APPDATA%\FreeCAD\Mod\
macOS:
FreeCAD 1.1:
~/Library/Application Support/FreeCAD/v1-1/Mod/FreeCAD 1.0:
~/Library/Application Support/FreeCAD/v1-0/Mod/
Linux:
Ubuntu:
~/.FreeCAD/Mod/or~/snap/freecad/common/Mod/(snap installs)Debian:
~/.local/share/FreeCAD/ModArch / CachyOS (FreeCAD 1.1 from
extra/freecad):~/.local/share/FreeCAD/v1-1/Mod/
Copy the addon/CADPilot directory into the addon directory:
git clone https://github.com/LBurny/cadpilot.git
cd cadpilot
# Linux (Ubuntu/Debian)
mkdir -p ~/.FreeCAD/Mod/
cp -r addon/CADPilot ~/.FreeCAD/Mod/
# macOS (FreeCAD 1.1)
mkdir -p ~/Library/Application\ Support/FreeCAD/v1-1/Mod/
cp -r addon/CADPilot ~/Library/Application\ Support/FreeCAD/v1-1/Mod/
# Windows (PowerShell, FreeCAD 1.1)
Copy-Item -Recurse addon/CADPilot "$env:APPDATA\FreeCAD\v1-1\Mod\"Restart FreeCAD, select CADPilot from the workbench list, and start the RPC server with the Start RPC Server command in the CADPilot toolbar. To start it automatically on every launch, enable Auto-Start Server in the CADPilot menu.
Step 2: Install the MCP server
Option A: PyPI (recommended)
With uv installed, no explicit install is needed, since uvx fetches the package from PyPI on first use:
uvx cadpilotOr with pip: pip install cadpilot
Option B: From source
git clone https://github.com/LBurny/cadpilot.git
cd cadpilot
uv syncThen use this MCP client configuration instead of the one below, and replace /path/to/cadpilot with the actual clone path (--no-sync skips the editable rebuild on every launch, which would fail while another server instance is running):
{
"mcpServers": {
"cadpilot": {
"command": "uv",
"args": ["--directory", "/path/to/cadpilot", "run", "--no-sync", "cadpilot"]
}
}
}The server speaks MCP on stdio and connects to FreeCAD's XML-RPC addon on localhost:9875. You normally don't run it by hand; your AI client launches it via the configuration below.
Client setup
All MCP clients that support stdio servers use the same configuration: command uvx, args ["cadpilot"]. Paste this snippet into your client's MCP configuration (Claude Code, Kimi Code, Cherry Studio, ZCode, Claude Desktop, Cursor, …):
{
"mcpServers": {
"cadpilot": {
"command": "uvx",
"args": ["cadpilot"]
}
}
}Startup options
Tool responses are text-only; the get_view tool captures a view screenshot on demand. Each capture is written under ~/.cadpilot/screenshots/ (newest 100 kept) and the response carries only its file path, so no image data enters the context; a multimodal client opens the PNG with its own file-reading tool. Startup flags:
--only-text-feedback: never return screenshots, even when requested (hard guarantee for text-only models)--host <ip>: connect to a FreeCAD instance on another machine--no-auto-audit: skip the connectivity audit after each mutation (for very large models)
Flags are appended to the args list, for example:
{
"mcpServers": {
"cadpilot": {
"command": "uvx",
"args": ["cadpilot", "--only-text-feedback"]
}
}
}Remote connections
By default the RPC server listens on localhost only. To control FreeCAD from another machine:
In the CADPilot toolbar, enable Remote Connections (the server binds to
0.0.0.0on next restart) and click Configure Allowed IPs to enter a comma-separated list of allowed IP addresses or CIDR subnets, e.g.192.168.1.100, 10.0.0.0/24. Only listed addresses can connect; restart the RPC server after changing settings.Point the MCP server at that machine:
"args": ["cadpilot", "--host", "192.168.1.100"].
Troubleshooting
Something not talking? Ask the AI to run the diagnose tool. It checks the RPC port, the FreeCAD process, the addon install and its logs (Windows/macOS/Linux), ends with a concrete fix, and works even when FreeCAD is frozen or not running. The two rules that solve most cases:
Addon changes load only at startup, so restart FreeCAD after installing or updating the addon.
The MCP tool list is built at startup, so restart the MCP client after changing the server config or version.
If every document call times out while
pingstill answers, a modal dialog (typically FreeCAD's document-recovery dialog after an unclean shutdown) is holding the queue;diagnose(dismiss=true)closes it with Cancel semantics.
Tools
cadis the unified CAD mutation tool:create_object/edit_object/delete_object/batch, parametric feature ops (boolean/fillet/chamfer/loft/sweep/mirror/pattern/move), appearance (color: shape color, transparency, line and display settings, for one object or the whole document), Sketcher/PartDesign ops (variables/sketch/pad/pocket/revolution/groove/thickness/draft/datum_plane/hull). Edge/face selectors are fed byget_topology; every mutation is transactional and rollback-able.execute_code/execute_code_async/get_task_resultrun arbitrary Python in FreeCAD (GUI-thread safe), or background-safe code for long OCCT computations with polling. A run that changes the document is transactional, so it rolls back and replays like any other step; a failing snippet is rolled back cleanly.Modeling sessions:
session(actionsstart/status/get_steps/rollback/redo/add_note/pause/resume/list/complete): step recording with rollback via FreeCAD's native transaction undo.Step planning & journal:
step_plansubmits a modeling plan to the FreeCAD-side journal without executing it;step_controldrives the review loop shared with the Steps panel:run_next/run_all/run_to/rollback_to/reexecute/accept/reject/update/insert/replay/snapshot/clear_plan/reset. The journal lives on the document itself, so the panel works even with the RPC server stopped.Knowledge hierarchy:
save_pattern/recall_patterns(reusable workflow memory),inspect_freecad(runtime API introspection),operation_help(per-operation reference docs).Geometry sensing:
measure_geometry/get_topology/check_interference/get_positioning_info: quantitative feedback after each modeling step.Assembly:
get_anchors/set_anchors/assemble/align_shapes/verify_assemblyfor data-driven spatial positioning;assembly_sessionfor mate-based assembly with persistent joints (FreeCAD 1.1 Assembly workbench) and declarative priority trimming.Documents & views:
create_document/list_documents/get_objects(passobj_namefor one object's properties) /get_view(the only screenshot tool; captures capped at 384 px on the long edge by default).Diagnostics:
diagnose(cross-platform fault probing that works with FreeCAD down) andget_addon_log(the addon's ring-buffer debug log, readable while the GUI is wedged).
See the design document for the architecture behind these tools, and try the demo model examples/Backpack.FCStd in FreeCAD.
Documentation
Development
git clone https://github.com/LBurny/cadpilot.git
cd cadpilot
uv sync
uv run pytest # run the test suite
uv run ruff check . # lint
uv run cadpilot # run the MCP server from sourceTwo layers of tests back the tool surface. The unit suite runs without FreeCAD: it includes a wire-contract test that compares every copy of the XML-RPC interface (client proxy, addon handler, test double) so a renamed method or a changed argument count fails in CI instead of at runtime. tests/live_complex_verify.py is the live half: complex real-scenario builds (a parametric flange, a shelled enclosure, a hinge assembly, journal and session semantics) that assert analytic volumes against a running FreeCAD, and each stress round adds its cases there instead of writing throwaway probes. Run it with FreeCAD open:
.venv/Scripts/python.exe tests/live_complex_verify.py # Windows; needs FreeCAD + the addon runningAcknowledgments
This project was originally based on neka-nat/freecad-mcp by Shirokuma (k tanaka). Many thanks to the original authors; parts of this project are derived from their work (MIT License).
License
MIT, see LICENSE.
Available Tools
27 toolsalign_shapesADestructive
Move an object so the chosen element aligns with an element of the target.
Args:
element / element_index: Element on the object to move.
target_element / target_element_index: Element on the target.
mode: touch (face to face, normals opposing), center (centers coincide) or axis (cylindrical axes aligned).
offset: Extra distance along the target normal; positive moves away.
Inputs: element (required), doc_name (required), obj_name (required), target_obj (required), +5 more. Returns: result
assembleADestructive
Snap parts together by matching named anchors in one transaction. For persistent joints use assembly_session.
Args:
mates: Non-empty list of mate dicts.
tolerance: Maximum allowed post-move residual in mm (default 0.1).
stop_on_error: Stop at the first failed mate (mates already applied stay; nothing moves only if the FIRST mate fails).
Reference: operation_help("assemble").
Inputs: mates (required), doc_name (required), tolerance, stop_on_error. Returns: result
assembly_sessionADestructive
Persistent-joint assembly on FreeCAD's Assembly workbench; prefer it over the one-shot assemble when joints must survive later moves.
Workflow: start(ground=part), add_component(part), mate(a, b, joint_type, trim?), solve, verify, complete. Moving a parent part and re-solving moves the children. rollback(to_step) restores placements atomically. A mate ref is {"part": <name>} plus exactly one of face="FaceN", anchor=<name> or point=[x,y,z].
Reference: operation_help("assembly_session").
Inputs: operation (required), a, b, name, +7 more. Returns: result
cadADestructive
Run one CAD modeling operation; the unified mutation entry point.
obj_name is the BASE object, except for loft/sketch/variables/datum_plane/hull (the NEW object); params go in obj_properties. Committed mutations are rollback-able session steps.
Args:
obj_type: Object type for create_object, e.g. "Part::Box".
ops: Operation dicts for batch.
stop_on_error: Stop a batch at the first failure.
description: One-line purpose of the step; the Steps panel's row label.
Reference: operation_help("<operation>").
Inputs: doc_name (required), operation (required), ops, obj_name, +4 more. Returns: result
check_interferenceARead-onlyIdempotent
Check two objects for interference: the distance between them and their common volume. Use it to verify clearance or detect collisions.
Returns: JSON distance_mm, intersects, common_volume_mm3.
Inputs: obj_a (required), obj_b (required), doc_name (required). Returns: result
create_documentA
Create a new FreeCAD document.
Args:
name: Document name. FreeCAD may sanitize or deduplicate it, so read the actual name from the result.
Inputs: name (required). Returns: result
diagnoseA
Find out why CADPilot cannot reach FreeCAD; works while FreeCAD is down.
Probes the RPC port, the process, the addon install and its logs.
Args:
host: FreeCAD host to probe; defaults to this server's --host.
dismiss: Also close the modal dialog blocking every call (Cancel, nothing confirmed).
Reference: operation_help("diagnose").
Inputs: host, dismiss. Returns: result
execute_codeADestructive
Run Python in FreeCAD's GUI thread (FreeCAD/App, FreeCADGui, Part pre-imported); print() output is returned.
The run is transactional: a mutating snippet commits as one undoable step, a read-only run is not recorded.
Args:
code: Code to run; start with a # comment naming the step, which becomes the step's row label and description.
doc_name: Bind the transaction, step journal and App.ActiveDocument to this document; defaults to the session's document, else the process's home document.
Inputs: code (required), doc_name. Returns: result
execute_code_asyncADestructive
Run Python on a background thread and return a task_id; poll the result with get_task_result.
The code must not touch the GUI: no FreeCADGui, views or selection, document objects, recompute or save; use execute_code for those. Output goes through task_print(...); print() is not captured.
Args:
code: Background-safe Python code.
Inputs: code (required). Returns: result
get_addon_logARead-onlyIdempotent
Read the addon's ring-buffer debug log (newest last) while FreeCAD is wedged or a call misbehaves.
Args:
level: Minimum level: DEBUG, INFO, WARNING or ERROR.
grep: Substring filter over message and detail.
since_seq: Only records after this sequence number.
limit: Max records (default 100).
Reference: operation_help("get_addon_log").
Inputs: grep, level, limit, since_seq. Returns: result
get_anchorsARead-onlyIdempotent
List an object's assembly anchors in GLOBAL coordinates. Auto-derived ones (bbox_center/min/max, com, axis_mid/start/end for the dominant cylindrical face, face0..2_center for the largest planar faces) merge with set_anchors ones, and explicit wins. Call it before placing parts and plan mates from the returned numbers; never guess coordinates.
Returns: JSON with anchors as {name: {pos, dir, source: "auto" | "explicit"}}.
Inputs: doc_name (required), obj_name (required). Returns: result
get_objectsARead-onlyIdempotent
List a document's objects, or read one object's full properties.
Args:
obj_name: Omit to list the objects; pass a name to read that object instead.
limit/offset: Page size and start index for the object list.
Inputs: doc_name (required), limit, offset, obj_name. Returns: result
get_positioning_infoARead-onlyIdempotent
One face, edge or vertex in global coordinates: center, normal, axis, radius, endpoints; the Placement is already applied. Prefer it over get_topology for precise positioning before alignment or assembly.
Args:
element: Which kind: face, edge or vertex.
element_index: 0-based index; call get_topology to find the indices.
Inputs: element (required), doc_name (required), obj_name (required), element_index (required). Returns: result
get_task_resultARead-onlyIdempotent
Poll the status and captured output of one execute_code_async task.
Args:
task_id: Task ID returned by execute_code_async.
Returns: JSON {status: running | done | error, output, traceback}.
Inputs: task_id (required). Returns: result
get_topologyARead-onlyIdempotent
List an object's topology for selection: faces by area, edges by length, vertices by distance, largest first. The names (Face1, Edge3, ...) feed fillet, boolean, sketch-on-face and friends.
Args:
element: Which kind to list: faces, edges or vertices.
limit: Max entries (1 to 200, default 50).
offset: How many entries to skip.
Returns: total, returned, and a '{element}' list of {index, name, type, area or length, center, planar-face normal}.
Inputs: doc_name (required), obj_name (required), limit, offset, +1 more. Returns: result
get_viewARead-onlyIdempotent
Capture one document's view and return the saved PNG's path.
Costly in context: reserve it for visual checks; prefer get_objects or measure_geometry for numbers. Without width/height the long edge is capped at 384 px.
Args:
view_name: Camera view, one of the nine names.
width/height: Pixel size; a smaller image saves context.
focus_object: Fit this object; the default frames everything.
doc_name: Frame this document; another agent may have switched the foreground tab.
Inputs: view_name (required), width, height, doc_name, +1 more. Returns: result
inspect_freecadARead-onlyIdempotent
Inspect the live FreeCAD Python API; the last resort when your own knowledge and recall_patterns are insufficient.
With doc_name and obj_name you get an object's TypeId, settable properties, methods and docstring. With dotted_name (e.g. "Part.makeLoft") you get a docstring or a member list.
Inputs: doc_name, obj_name, dotted_name. Returns: result
list_documentsBRead-onlyIdempotent
List the open FreeCAD documents.
Args:
limit/offset: Page size and start index.
Inputs: limit, offset. Returns: result
measure_geometryARead-onlyIdempotent
Measure an object's Shape (the object must have one) to verify a design target numerically.
Returns: JSON volume_mm3, area_mm2, bbox, center_of_mass, element counts, is_valid, shape_type. Numbers carry 6 significant digits; the bbox is OCC's bound box, exact for planar shapes and within about 0.1 mm on curved ones.
Inputs: doc_name (required), obj_name (required). Returns: result
operation_helpARead-onlyIdempotent
Full parameter reference for a cad() operation or another topic. Call it with an operation name such as "sketch", or with no argument for the topic list.
Inputs: operation. Returns: result
recall_patternsARead-onlyIdempotent
Search the pattern memory for workflows or code like your task; do this before trial and error when your knowledge may not cover it.
Args:
query: Keywords describing the task, e.g. "boolean cut holes cylinder".
limit: Max results (default 3).
Returns: JSON list of matching patterns with code/steps.
Inputs: query (required), limit. Returns: result
save_patternA
Store a reusable modeling pattern for later recall; call this after a non-trivial approach worked.
Args:
name: Short name, e.g. "flanged pipe via loft".
description: What it does and when to use it.
code: Optional Python snippet that implements it.
tags: Retrieval tags.
Returns: The stored pattern_id.
Inputs: name (required), description (required), code, tags. Returns: result
sessionADestructive
A modeling session bound to a document; cad() mutations become transaction-backed steps you can roll back or redo.
Actions: start (doc_name, create_document?) | status | get_steps (limit/offset) | rollback (to_step, force?) | redo (n?) | add_note (note, note_type?) | pause | resume (session_id) | list | complete (save?, save_path?, description?, tags?).
Reference: operation_help("session").
Inputs: action (required), n, name, note, +12 more. Returns: result
set_anchorsADestructive
Define named anchors on an object. They persist with the document, move with its Placement, and the write becomes a modeling-session step.
Args:
anchors: {name: {"pos": [x, y, z], "dir": [x, y, z] | null}}.
replace: Replace all existing anchors instead of merging.
coord_frame: local stores values as given; global converts them first, for global source coordinates.
Inputs: anchors (required), doc_name (required), obj_name (required), replace, +1 more. Returns: result
step_controlBDestructive
Review, run and undo the steps of a document's step journal.
Actions: run_next | run_all | run_to | rollback_to | reexecute | accept | reject | update | insert | replay | snapshot | clear_plan | reset (needs confirm=true) | status.
Reference: operation_help("step_control").
Inputs: action (required), doc_name (required), force, index, +2 more. Returns: result
step_planA
Submit a modeling plan to the document's step journal without executing it.
Each step is a cad() argument dict and waits for release in the CADPilot Steps panel or via step_control.
Reference: operation_help("step_plan").
Inputs: steps (required), doc_name (required), description. Returns: result
verify_assemblyARead-onlyIdempotent
Audit a document's spatial health, read-only: floating parts, interferences, and anchor-pair distances. Hidden objects are skipped. Trust these numbers over a screenshot.
Args:
checks: Optional anchor-pair distance checks.
float_threshold: Gap in mm above which a part counts as floating (default 1.0).
interference_min_volume: Smallest common volume in mm3 worth reporting.
Returns: JSON floating/interferences/checks lists and a summary.
Inputs: doc_name (required), checks, float_threshold, interference_min_volume. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 27 tools
Most tools have distinct roles: cad vs execute_code, execute_code vs execute_code_async, and assemble vs assembly_session are clearly differentiated by scope and persistence. Some overlap remains among session, step_plan, step_control, and rollback-related operations, but descriptions provide enough guidance to select correctly.
The surface is predominantly snake_case, but conventions are mixed: many tools use verb_noun (create_document, get_topology), while several use bare nouns or vague labels (session, cad, step_plan, assembly_session). It remains readable, but there is no single predictable pattern.
At 27 tools the set is heavy for the rubric's 3-15 sweet spot, with multiple clusters covering overlapping concerns (sessions/step journals, code execution, assembly workflows). Several capabilities could likely be consolidated, so the count exceeds what feels well-scoped.
Coverage is broad: document creation/listing, modeling via cad, code execution, step planning/control, diagnostics, measurement, topology, alignment, anchors, and both one-shot and persistent assembly. Minor lifecycle gaps exist (e.g., explicit document close/delete or general import/export), but agents can work around them.
Maintenance
Related MCP Connectors
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Build and update complete applications in Apper through AI assistants using MCP.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to perform 3D modeling and CAD operations in FreeCAD, including geometry creation, boolean operations, and document management.79MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with FreeCAD for 3D modeling, macros, and debugging via MCP.MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI to directly call FreeCAD for 3D modeling via the MCP protocol, providing 39 modeling tools including primitive creation, boolean operations, transformations, and export.3-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to programmatically build, analyze, and export 3D CAD geometry using FreeCAD through REST or MCP tools.MIT