FreeCAD MCP: AI-Driven CAD with Claude (2026 Guide)

TL;DR + what you actually need

Four things that get you from zero to AI-driven CAD:

• FreeCAD itself — 1.0 or 1.1, running with the GUI open. There is no headless mode (it’s an open feature request).
• The FreeCADMCP addon — copied from the repo’s addon/FreeCADMCP folder into your FreeCAD Mod directory. It adds an “MCP Addon” workbench with a Start RPC Server button. That button is the half everyone forgets.
• The MCP server — the freecad-mcp Python package, run via uvx (so you need uv installed). No API keys, no accounts — everything runs on your machine.
• One flag worth knowing: --only-text-feedback. By default every tool call returns a screenshot, which is great for accuracy and brutal on token usage. Add the flag for long sessions.

The client config, if you only came for the copy-paste:

{
  "mcpServers": {
    "freecad": {
      "command": "uvx",
      "args": ["freecad-mcp"]
    }
  }
}

The rest of this guide explains the two-process architecture, walks every tool, and covers the failure modes pulled from the repo’s real GitHub issues. Canonical catalog entry with live install configs: /servers/freecad.

What FreeCAD MCP actually does

FreeCAD MCP, by neka-nat (MIT licensed), connects an MCP client — Claude Desktop in the README, but any MCP client works — to a live FreeCAD session. FreeCAD is the open-source parametric CAD application: parts are defined by editable parameters and a feature history, not frozen meshes. That matters here, because it means the agent isn’t generating a blob of triangles — it’s building real CAD objects you can keep editing by hand afterwards.

The README demos show the shape of what’s possible, and they’re worth watching before you install:

• Design a flange. An animated capture of Claude building a bolt-hole flange step by step — cylinders, boolean cuts, a hole circle — checking a screenshot after each operation.
• Design a toy car. A multi-part assembly (body, wheels) built conversationally in the same screenshot-verify loop.
• Design a part from a 2D drawing. The most striking one: the input is a PNG of a dimensioned 2D drawing, and Claude models the 3D part from it. The repo links the full Claude conversation so you can read exactly which tool calls it made.

The design choice that makes all three work is the screenshot feedback loop. Mutating tools (create_object, edit_object, execute_code…) return a rendered screenshot of the 3D view alongside the text result. The model sees the geometry it produced, notices the boss is on the wrong face, and fixes it in the next call. Without that loop, AI CAD is blind geometry generation; with it, it’s an iterate- and-verify workflow.

The maintainer, Kenta Tanaka (@neka_nat), is a robotics engineer, and his framing of why this matters goes beyond CAD — a few weeks after shipping freecad-mcp he drew the parallel between MCP and ROS, the robot operating system: one motor needs no framework, but dozens of components do, and the endgame is agents wielding hundreds of tools at once:

Two processes, one bridge

Most MCP servers are a single process your client launches. FreeCAD MCP is two, and understanding the split saves you every debugging session later:

Claude Desktop / Cursor / Claude Code
        │  MCP over stdio
        ▼
freecad-mcp  (Python package, launched by your client via uvx)
        │  XML-RPC on localhost:9875
        ▼
FreeCADMCP addon  (workbench running INSIDE the FreeCAD GUI)
        │  FreeCAD Python API
        ▼
Your open FreeCAD document + 3D view

The named pieces:

• The MCP server (freecad-mcp on PyPI) speaks MCP to your client over stdio and translates tool calls into XML-RPC requests. XML-RPC is an old, simple remote-procedure-call protocol — a good fit because FreeCAD bundles its own Python and you can’t pip-install MCP dependencies into it cleanly.
• The addon (FreeCADMCP) is a FreeCAD workbench that hosts the XML-RPC listener on port 9875 and executes operations on the GUI thread — object creation, property edits, screenshots of the active view.
• The parts library (optional) is FreeCAD’s community parts library addon. With it installed, the agent can browse and insert ready-made parts — screws, bearings, profiles — instead of modeling them from primitives.

The consequence of the split: both halves must be alive. FreeCAD open but RPC server not started → connection errors. RPC running but the client config missing → no tools in Claude. Every “it doesn’t work” report in the repo’s issues resolves to one of those two states more often than anything else.

Setup part 1: the FreeCAD addon

Clone the repo and copy the addon folder into FreeCAD’s Mod directory. The directory moves around by platform and FreeCAD version — this table is the part to get right:

git clone https://github.com/neka-nat/freecad-mcp.git
cd freecad-mcp

# macOS, FreeCAD 1.1:
cp -r addon/FreeCADMCP ~/Library/Application\ Support/FreeCAD/v1-1/Mod/

# Ubuntu:
cp -r addon/FreeCADMCP ~/.FreeCAD/Mod/

Restart FreeCAD, pick MCP Addon from the workbench dropdown, and click Start RPC Server in the FreeCAD MCP toolbar. The listener binds to localhost:9875. Two settings worth enabling from the same menu:

• Auto-Start Server — starts the RPC server on every FreeCAD launch (saved to freecad_mcp_settings.json). Turn this on; the manual button is the thing you will forget.
• Remote Connections — rebinds to 0.0.0.0 so another machine can drive this FreeCAD instance. Access is restricted to the IPs/CIDR ranges you whitelist under Configure Allowed IPs (default 127.0.0.1). On the client side you pass --host 192.168.1.100 in the server args. Useful for a CAD workstation + laptop setup; leave it off otherwise.

Setup part 2: the MCP server (every client)

The server is stdio-only — your client launches uvx freecad-mcp as a subprocess. The install panel below pulls configs from the canonical /servers/freecad catalog entry: pick your client, copy, paste, restart.

One-line install · FreeCAD

Open server page

Install

Cursor

One-click install

1-Click

VS Code

One-click install

1-Click

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

Client-specific notes:

• Claude Desktop — add the JSON block to claude_desktop_config.json (the README’s reference client). See /clients/claude-desktop for the file location per OS.
• Claude Code — claude mcp add freecad -- uvx freecad-mcp. Pair it with a CLAUDE.md note telling the agent to verify geometry with get_view before declaring a part done.
• Cursor / VS Code / Windsurf — same JSON shape in ~/.cursor/mcp.json or the client’s MCP settings. See /clients/cursor.
• Token-saver variant — append "--only-text-feedback" to the args array to suppress per-call screenshots.
• Developer mode — run from a clone with uv --directory /path/to/freecad-mcp run freecad-mcp if you want to hack on the server itself.

Verification: with FreeCAD running and the RPC server started, ask the agent “create a document called Test and put a 10×10×10 box in it.” You should see the box appear in FreeCAD and (without the text-only flag) a screenshot come back in the chat.

Tools walkthrough

Eleven tools, small enough to keep entirely in your head. Grouped by what they do:

Build and edit

• create_document — new FreeCAD document. Everything else takes a doc_name.
• create_object — the workhorse. Creates typed objects: Part::Box, Part::Cylinder, Draft::Circle, PartDesign::Body, plus FEM types (analyses, constraints, materials, Gmsh meshes). Takes a properties dict — dimensions, placement with rotation, even ViewObject color.
• edit_object — mutate properties of an existing object; the fallback when a shape needs adjusting rather than recreating.
• delete_object — remove an object by name.
• execute_code — run arbitrary Python inside FreeCAD. The escape hatch that makes everything not covered by the typed tools possible: booleans, sketches, exports, batch edits. More below — it’s both the most powerful tool and the security boundary.

Inspect

• get_view — screenshot of the active 3D view from a named camera: Isometric, Front, Top, Right, Back, Left, Bottom, Dimetric, Trimetric.
• get_objects / get_object — the document tree and per-object properties. The agent uses these to re-orient mid-session instead of guessing what exists.

Reuse and simulate

• get_parts_list / insert_part_from_library — browse and drop in parts from the FreeCAD parts library addon.
• run_fem_analysis — runs the CalculiX solver (FreeCAD’s bundled finite-element solver) on an existing analysis and returns max von Mises stress, max displacement, and node count. The repo’s cantilever example shows the full loop: geometry → material → constraints → mesh → solve.

Opinionated take: the typed tools exist so the model doesn’t have to write Python for the common 80%, and the screenshots they return are what keep it honest. But anything genuinely parametric — a bolt-hole circle, a swept profile — ends up in execute_code. Expect your sessions to be roughly half typed calls, half generated Python.

Recipes

Recipe 1 — Parametric part from a description

The flange demo, reproduced. Prompt: “Create a flange: outer diameter 120 mm, bore 40 mm, thickness 12 mm, with 6 M8 bolt holes on a 90 mm bolt circle. Show me the isometric view when done.” The agent creates the base cylinders via create_object, then drops to execute_code for the polar hole pattern and boolean cut. Give exact dimensions — the model is good at geometry construction and bad at inventing sensible engineering numbers.

Recipe 2 — Batch-modify an existing model

Parametric edits across many objects is where execute_code beats clicking. Prompt: “In the open document, find every cylinder with radius 4 mm and change it to 4.2 mm for clearance.” The agent runs get_objects to enumerate, then one Python loop:

doc = App.getDocument("MyPart")
for obj in doc.Objects:
    if obj.TypeId == "Part::Cylinder" and abs(obj.Radius.Value - 4.0) < 1e-6:
        obj.Radius = 4.2
doc.recompute()

Recipe 3 — The screenshot verify loop

For anything non-trivial, make the loop explicit in your prompt: “After each feature, check the Front and Top views and confirm the geometry matches the drawing before continuing.” This is exactly how the 2D-drawing demo works — the model compares get_view output against the input drawing and corrects itself. It costs tokens (each view is an image) but multiplies reliability on multi-step parts. Run expensive sessions with screenshots on; do bulk scripted work with --only-text-feedback.

Recipe 4 — Export STEP / STL

No dedicated export tool exists yet (it’s an open feature request), but FreeCAD’s Python API covers it through execute_code:

import Part, Mesh
doc = App.getDocument("MyPart")
# STEP (exact CAD geometry, for other CAD tools):
Part.export([doc.Flange], "/Users/you/parts/flange.step")
# STL (mesh, for 3D printing):
Mesh.export([doc.Flange], "/Users/you/parts/flange.stl")

Ask for it in plain language — “export the body as STEP to ~/parts/” — and the agent writes this for you.

Limits (read before you commit a workflow to it)

• Token burn from screenshots. Every mutating call returns an image by default. A long modeling session can eat a surprising share of a Claude usage limit — “Excessive Token Usage Due to Image Returns” was a real issue in the repo, and --only-text-feedback is the fix it produced.
• GUI required. The addon lives in the FreeCAD GUI process and screenshots need an active 3D view. No headless / CI use today (open issue).
• execute_code is arbitrary code execution. By design. The model can write files, import modules, and touch anything your FreeCAD process can. Fine on your own workstation with your own prompts; think twice before combining it with Remote Connections on a shared network, and keep the allowed-IP list tight if you do.
• Geometric reasoning has a ceiling. Models handle primitives, booleans, and patterns well; heavily constrained sketches and complex fillet chains far less so. Even the maintainer is clear-eyed here — in an April 2026 comparison of AI CAD-code accuracy he noted that tools with more training-data coverage, like CadQuery, tend to win on precision. Treat FreeCAD MCP as a fast drafting partner that produces editable parametric starts, not a substitute for a CAD engineer on tolerance-critical parts.

Troubleshooting

Every entry below traces back to a real issue in the repo’s tracker.

Alternatives: Blender and OpenSCAD routes

FreeCAD MCP is the parametric-engineering option. Two adjacent tools cover the cases it handles poorly:

Blender — organic modeling and look-dev

If the goal is meshes, materials, animation, or anything sculptural, drive Blender instead. The blender-toolkit skill automates shape creation, materials, and Mixamo retargeting with real-time control; our Claude × Blender connector guide walks the full setup. The trade: Blender gives you no feature history — edits are destructive, where FreeCAD parts stay parametric.

OpenSCAD — code-first and headless

If you want deterministic, reviewable, version-controllable geometry — or generation without a GUI — the OpenSCAD skill is the better shape. OpenSCAD models are programs (CSG code), so the agent writes text, renders previews from multiple angles, validates syntax, and exports STL — no running desktop app required. That also makes it the workaround for FreeCAD MCP’s missing headless mode.

Within the FreeCAD MCP space itself there are other implementations (e.g. bonninr/freecad_mcp), but neka-nat’s is the most established and the one our catalog tracks. For the wider landscape of servers worth installing this year, see our awesome MCP servers roundup and the design category.

FAQ

Sources

• Primary — repository, README, and demo GIFs: github.com/neka-nat/freecad-mcp (MIT)
• Primary — shared Claude conversation for the 2D-drawing-to-part demo: claude.ai/share/7b48fd60…
• Primary — FEM example: examples/cantilever_fem.py
• Community — GitHub issues (token usage, connection failures, macOS workbench, snap/PySide2, Windows screenshots, headless request): github.com/neka-nat/freecad-mcp/issues
• Maintainer — MCP/ROS framing: @neka_nat, April 2025; AI CAD-code accuracy comparison: @neka_nat, April 2026
• Docs — uv/uvx installation: docs.astral.sh/uv/guides/tools; FreeCAD parts library: github.com/FreeCAD/FreeCAD-library
• Internal — canonical entry: /servers/freecad; skills: /skills/blender-toolkit, /skills/openscad