Freecad Mcp

What is Freecad Mcp about?

Freecad Mcp connects an AI agent to the FreeCAD application, allowing the agent to drive FreeCAD’s modeling, sketching, part‑design, drafting, boolean, transformation, measurement, and CAM workbenches. It acts as a collaborative partner: the user supplies intent and constraints, while the AI executes the FreeCAD commands, reads reports, and iterates.

How to use Freecad Mcp?

1. Clone the repository: git clone https://github.com/blwfish/freecad-mcp.git.
2. Install Python dependencies (e.g., via pip install -r requirements.txt).
3. Open FreeCAD (version 1.1.x for most tools; a weekly dev build for CAM) and enable the AICopilot workbench that the project installs as an add‑on.
4. Start the MCP server by launching FreeCAD; the addon automatically creates a Unix socket (/tmp/freecad_mcp_<uuid>.sock).
5. In your AI client, follow the instructions in AGENT‑INSTALL.md to point the agent to the socket, then issue high‑level commands such as list_freecad_instances, select_freecad_instance, or custom tool calls defined in TOOLS.md.
6. Verify installation by checking the Report View for lines like “AI Copilot Service starting” and “Socket server started / Claude ready”.

Key Features

• Full FreeCAD API access from an AI agent (Part, PartDesign, Sketch, Draft, Boolean, Transform, Measurement, CAM).
• Multi‑instance management: discover, list, select, and spawn multiple FreeCAD sessions via UUID or human‑readable label.
• Integrated diagnostics: operation logging, crash capture, report‑view inspection, and built‑in debugging runbooks.
• Cross‑platform support (macOS, Windows, Linux) with environment‑variable overrides for socket paths and instance labels.
• Extensive test coverage: 1.4 k unit tests and 147 integration tests, CI‑validated on every push.
• Security transparency: explicit documentation of full Python and filesystem access granted to the AI.

Use Cases

• Co‑designing a mechanical part (e.g., mounting plate with holes and fillets) where the AI iteratively refines geometry based on user feedback.
• Diagnosing sketch or constraint errors by having the AI read FreeCAD’s Report View and explain cryptic messages.
• Generating CNC toolpaths: the AI selects tools, sets parameters, and exports G‑code.
• Automating repetitive part families by creating macros that ingest spreadsheet dimensions.
• Validating models before release: geometry error checks, wall‑thickness analysis, collision detection.
• Working with imported meshes (STL) to add mounting features or convert to solid geometry.
• Exporting finalized designs to STEP, STL, or other manufacturing formats.

FAQ

Q: Which FreeCAD version do I need? A: All tools work on FreeCAD 1.1.x; CAM tools require a current weekly development build (e.g., 26.3.x).

Q: Can I run the server headless? A: Yes. Launch FreeCAD with the --console flag; the add‑on will still create the socket and be controllable via the AI.

Q: How does the AI get access to my filesystem? A: The MCP server runs inside FreeCAD’s Python environment, which has full OS access. Treat any FreeCAD file from an untrusted source as untrusted code.

Q: What if I have multiple FreeCAD windows open? A: Each instance generates a UUID and its own socket. Use list_freecad_instances and select_freecad_instance to choose the target.

Q: Is there a Node.js package to start the server? A: The project is a Python add‑on, not an npm package, so no npx command applies.

freecad-mcp

What This Does

This is a bridge between your AI agent and FreeCAD — a thinking partner for parametric design, CNC toolpath generation, and mesh work. You bring the design intent and the domain judgment; the agent handles the FreeCAD mechanics. Together: moving faster, co-designing things that would take hours to build by hand, untangling the cryptic error messages that FreeCAD is so good at generating, and hunting down the subtle, knotty modeling problems that are nearly impossible to find alone. Built for personal daily use — designing parts, generating toolpaths, printing and cutting them — not a demo. See TOOLS.md for the full tool reference.

What You Can Work On Together

• Work through a design — "I need a mounting plate — 100x60mm, four M3 holes, rounded corners. What's the right approach?" You bring the requirements and constraints; the agent builds, flags underspecified decisions, and iterates with you.
• Diagnose what went wrong — "I just tried to pad this sketch and got a weird result — what is FreeCAD actually telling me?" The agent can read the Report View, inspect sketch constraints, and explain what's happening in terms you can act on.
• Iterate on an existing part — "This wall feels too thin and the fillet might not survive printing — let's look at it together"
• Plan CNC toolpaths — "I want to mill this pocket — let's work out the right tool and parameters for the material"
• Build something reusable — "I keep doing this same workflow for every bracket — let's write a macro that generates them from a spreadsheet of dimensions"
• Check your work before committing — "Does this model have geometry errors?", "Will these walls survive printing?", "Are any of these parts going to collide?"
• Work with meshes — "I have an STL from the manufacturer — let's get it into FreeCAD and add mounting features"
• Export for manufacturing — "Export this as STEP and generate G-code for my CNC router"

See It In Action

These are a couple of examples of how I've used the MCP.

Debugging a broken external reference — a link FreeCAD can't restore, an error message that seems to contradict what you know about your own model, and a one-line fix found by reading the file directly.

Full story →

---

Designing a shingles generator — several sessions of back-and-forth to design a parametric generator that tiles any roof surface from a spreadsheet of parameters.

Full story →

---

Getting Started

FreeCAD version support: All tools except CAM are supported on FreeCAD 1.1.x (current stable). CAM toolpath generation requires a current FreeCAD weekly development build (what used to be called "1.2-dev" before upstream moved to calendar-based versioning, e.g. 26.3.x) — the Path workbench API changed incompatibly between 1.1 and the dev series. This project tracks the latest weekly.

Developed on macOS with Claude Code. The code handles macOS, Windows, and Linux — other platforms should work but are less tested. PRs for other agents and platforms will be considered. It's also been manually smoke-tested against LM Studio's native MCP client (qwen/qwen2.5-coder-14b, qwen/qwen3-32b, google/gemma-4-e4b) to confirm the protocol round-trips cleanly outside of Claude — see AGENT-INSTALL.md for details and caveats.

Tell your AI agent:

Go to https://github.com/blwfish/freecad-mcp and read the AGENT-INSTALL.md file. Follow the instructions to install and configure the FreeCAD MCP server on this machine.

Your agent will handle the rest — installing prerequisites, cloning the repo, setting up the FreeCAD addon, and registering itself. Once setup is complete, you can ask your agent to design parts.

Verifying your installation

Once FreeCAD is running with the AICopilot workbench loaded, open the Report View (menu: View → Panels → Report View). You should see something like this:

A few things worth knowing about this output:

• AI Copilot Service starting — confirms the AICopilot workbench loaded correctly. If you don't see this, the addon isn't installed or FreeCAD isn't finding it.
• Debug/crash infrastructure loaded — active instrumentation is running. If something goes wrong mid-operation, logs and crash reports are captured automatically.
• Socket server started / Claude ready — the bridge is listening. This is the line that means your AI agent can connect.
• Font alias warning (in orange) — harmless Qt noise that appears on most macOS systems regardless of what you're doing. Not a problem.

Running multiple FreeCAD instances

The MCP can talk to more than one FreeCAD at a time — useful for comparing a local debug build against a stock release, running a regression in a side window while keeping your main work open, or driving headless workers from the same Claude session.

Each FreeCAD process (GUI or headless) generates a UUID at startup, binds its own socket at /tmp/freecad_mcp_<uuid>.sock, and writes a discovery file to ~/.cache/freecad-mcp/instances/<uuid>.json. The bridge scans that directory to find live instances regardless of who launched them.

Optional env vars on launch:

• FREECAD_MCP_LABEL=<name> — give the instance a human-readable name (defaults to the UUID otherwise)
• FREECAD_MCP_SOCKET=<path> — override the socket path entirely (escape hatch for CI / tightly-scripted launches)

Listing and switching from the agent:

list_freecad_instances          # all live instances + active doc info
select_freecad_instance uuid=<id>           # by uuid
select_freecad_instance label="weekly"      # or by label

Spawning from the agent:

spawn_freecad_instance gui=true label="private" \
    freecad_binary=/path/to/your/private/build/bin/FreeCAD
spawn_freecad_instance gui=true label="weekly" \
    freecad_binary=/Applications/FreeCAD.app/Contents/MacOS/FreeCAD

Resolution rules when no instance is explicitly selected: 0 live → error, 1 live → auto-select, 2+ live → error listing them (call select_freecad_instance).

For Developers

# Unit tests (1430 tests, no FreeCAD required)
python3 -m pytest tests/unit/

# Integration tests (147 tests, requires running FreeCAD with AICopilot loaded)
python3 -m pytest tests/integration/

# All tests with coverage
python3 -m pytest --cov=AICopilot

Prompt Caching and Direct Claude API Calls

For Claude users: the easiest and cheapest approach is to use Claude Code, the web interface, or the CLI tool directly. These platforms automatically handle prompt caching and cost optimization — you don't need to think about it. If you're just using this MCP to design parts in FreeCAD, use Claude Code. Stop reading this section.

If you're building applications or integrations that make direct calls to the Claude API (using the Anthropic SDK), you must understand prompt caching. The Claude desktop app, web interface, and CLI tools automatically handle caching of file context and tool references — you don't see this optimization, but it reduces latency and cost for repeated queries over the same context.

When you make direct API calls, caching must be managed explicitly. The MCP server itself doesn't make API calls, but if you build integrations or extensions that do:

• Read the Anthropic SDK documentation on prompt caching before deploying
• Understand cache TTL (typically 5 minutes) and cost implications (20% of input tokens)
• Be aware that cache keys include model, system prompt, and exact token boundaries — small variations bust the cache
• Consider cache-busting risks if your context is frequently updated (like document state snapshots)

Similarly, if you integrate other MCP servers or agents into your workflow, they may have analogous considerations that are not documented in their README. Check their documentation or source for caching behavior, async job handling, and token limits — don't assume they work like Claude Code.

The test suite covers the handler dispatch layer, base infrastructure, and document operations via unit tests, plus end-to-end coverage of Part, PartDesign, Sketch, Draft, Boolean, Transform, Measurement, and CAM workflows via integration tests against a live FreeCAD instance. CI runs both suites on every push.

Built-in Diagnostics

The MCP includes operation logging, crash capture, and report view access. FreeCAD's own error reporting is often cryptic — OCCT kernel crashes leave no trace, and the messages that do appear require context to interpret. These tools provide that context.

Most users and developers won't know this infrastructure exists until they need it. See docs/diagnostics.md for a full guide with real examples, and AGENT-DEBUGGING.md for the step-by-step investigation runbook agents should follow when something goes wrong.

See AGENT-INSTALL.md for full technical details, architecture, contributing guidelines, and how to add new tools.

Security

This tool grants your AI agent full access to FreeCAD's Python environment, including the filesystem and OS — this is by design. It also means the agent reads document content (object labels, macro source, spreadsheet values) directly into its reasoning context, so treat FreeCAD files from untrusted sources the same way you'd treat untrusted code. See SECURITY.md for the full security model, practical mitigations, and how to report vulnerabilities.

The MCP also checks GitHub once a day for a newer release — a plain pull against GitHub's public API, cached, and logged locally to ~/.cache/freecad-mcp/version_check.log so it's auditable. See SECURITY.md for details.

Issues

If you hit a bug, open an issue — silent failures don't help anyone. Agents won't tell you when something's wrong; they'll just fail the task. See CONTRIBUTING.md for what makes a useful report.

License

LGPL-2.1-or-later