Skip to main content
Glama
CADPilot
by LBurny

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_code is 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 diagnose tool 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_log reads 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/Mod

    • Arch / 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

With uv installed, no explicit install is needed, since uvx fetches the package from PyPI on first use:

uvx cadpilot

Or with pip: pip install cadpilot

Option B: From source

git clone https://github.com/LBurny/cadpilot.git
cd cadpilot
uv sync

Then 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:

  1. In the CADPilot toolbar, enable Remote Connections (the server binds to 0.0.0.0 on 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.

  2. 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:

  1. Addon changes load only at startup, so restart FreeCAD after installing or updating the addon.

  2. The MCP tool list is built at startup, so restart the MCP client after changing the server config or version.

  3. If every document call times out while ping still 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

  • cad is 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 by get_topology; every mutation is transactional and rollback-able.

  • execute_code / execute_code_async / get_task_result run 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 (actions start / 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_plan submits a modeling plan to the FreeCAD-side journal without executing it; step_control drives 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_assembly for data-driven spatial positioning; assembly_session for mate-based assembly with persistent joints (FreeCAD 1.1 Assembly workbench) and declarative priority trimming.

  • Documents & views: create_document / list_documents / get_objects (pass obj_name for 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) and get_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 source

Two 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 running

Acknowledgments

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 tools
align_shapesA
Destructive

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

assembleA
Destructive

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_sessionA
Destructive

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

cadA
Destructive

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_interferenceA
Read-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_codeA
Destructive

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_asyncA
Destructive

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_logA
Read-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_anchorsA
Read-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_objectsA
Read-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_infoA
Read-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_resultA
Read-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_topologyA
Read-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_viewA
Read-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_freecadA
Read-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_documentsB
Read-onlyIdempotent

List the open FreeCAD documents.

Args:
    limit/offset: Page size and start index.

Inputs: limit, offset. Returns: result

measure_geometryA
Read-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_helpA
Read-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_patternsA
Read-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

sessionA
Destructive

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_anchorsA
Destructive

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_controlB
Destructive

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_assemblyA
Read-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

    A3.6/5.0

    Scored across 27 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to programmatically build, analyze, and export 3D CAD geometry using FreeCAD through REST or MCP tools.
      MIT