Skip to content

v0v1kkk/freecad-engineering

v0.1.0MIT

Editable, evidence-backed FreeCAD modeling and small-part engineering workflows for AI agents.

GitHubOpen Website

FreeCAD Engineering

This is my experimental kit for doing small mechanical projects with FreeCAD and an AI agent. It grew out of real modeling sessions: a parametric laptop stand, several attempts at a printed snap-fit, imported STL assemblies, an FDM bracket, and a simple FEM cantilever check.

The part I care about most is editability. A new model should normally look like something a FreeCAD user would build: documented values in a Spreadsheet, fully constrained Sketches, named PartDesign features, and expressions that keep the design intent visible. A finished Part::Feature blob may be quick for an agent to produce, but it is miserable for a person to take over later.

The plugin packages 13 Agent Skills and declares the external freecad-mcp server. The server is not bundled and nothing is installed automatically.

What is in the bundle

The freecad-engineering meta-skill routes work through the other skills:

  • FreeCAD setup, MCP diagnostics, scripting, native parametric modeling, model validation, and imported-geometry audit;
  • contact and motion reasoning, first-order strength checks, FDM-specific review, and a guarded FreeCAD FEM workflow;
  • STEP parts, G-code, and a browser-based CAD viewer.

The skills share one evidence rule: a missing check is not_tested, not a pass. A successful CAD inspection does not prove that a snap-fit will retain a board, that an FDM bracket will survive creep, or that a FEM result represents the physical part. A failed physical test wins over an earlier analytic candidate.

Prerequisites

  • FreeCAD 1.0 or newer; 1.1 is recommended for the tested workflow.
  • Python 3.11 or newer for the bundled validation helpers.
  • A client that can load Agent Skills and stdio MCP servers.
  • Optional tools for specific workflows: CalculiX and Gmsh for the current FEM beta, a slicer for G-code checks, Node.js for CAD Viewer, and Elmer if you deliberately choose to set it up.

Elmer is not required for ordinary CAD work. The bootstrap skill detects it and explains the options, but does not install it.

Install the plugin

This repository follows the portable Agent Plugins 1.0.0 layout. That specification is still a Working Draft, and client installation UX is outside its scope. Use your client's Agent Plugins import or marketplace flow and point it at a tagged release of this repository when possible.

Some clients expose Agent Skills and MCP configuration separately rather than installing a root plugin.json directly. In that case, install the folders under skills/ through the client's normal skill mechanism and register the root mcp.json as a stdio server. Do not replace the bundle with a mutable link to somebody else's authoring checkout.

One concrete example matters here: the current Codex local-marketplace docs use a client-specific .codex-plugin/plugin.json. This repository deliberately does not include that adapter. Its portable plugin.json remains the source format; the Codex test below loads the same skills and MCP declaration through Codex's component mechanisms.

Set up FreeCAD MCP

The declared command is the bare executable freecad-mcp, so it must be on the client's PATH. The upstream project currently supports a disposable launch with uvx freecad-mcp; this plugin needs a persistent command instead:

uv tool install freecad-mcp
command -v freecad-mcp

That is the convenient route, not a security requirement. If you prefer to review and pin the source, clone neka-nat/freecad-mcp, check out a chosen commit, inspect it, and install that checkout with your normal Python tooling. Package trust and update policy belong to you and your system, not to the Agent Plugins format.

The MCP process also needs the matching FreeCAD add-on. FreeCAD's actual user data directory varies by operating system, package, and FreeCAD version. Run the read-only probe before copying anything:

python skills/freecad-engineering-bootstrap/scripts/bootstrap_probe.py

Then follow the upstream add-on instructions for the reported UserAppData/Mod directory, restart FreeCAD, switch to the MCP workbench, and start or enable its RPC server. The bootstrap skill has a provider matrix and a source-build path for people who do not want the PyPI package.

First run

  1. Start FreeCAD and open a disposable document.
  2. Confirm that freecad-mcp is on the same PATH your agent client inherits.
  3. Ask the client to list the FreeCAD tools and read the active document.
  4. Use a harmless scratch operation, then inspect and delete the scratch document.
  5. Start a real design through freecad-engineering, with requirements and acceptance checks written before geometry changes.

The MCP exposes arbitrary FreeCAD Python execution. Read generated code before running it, keep credentials and unrelated files out of scope, and use copies or undo checkpoints before risky mutations.

Current verification

The 0.1 bundle has regression fixtures for the snap-fit v5/v6/v7.1 history, an imported-mesh placement case, an FDM bracket, a normalized FEM result, and a native-parametric laptop stand. The laptop model was exercised through FreeCAD 1.1.1 with a baseline, parameter perturbation, restore, save, and reopen cycle.

On 2026-08-12, the bundle passed the official Agent Plugins 1.0.0 schemas, the official Agent Skills validator for all 13 skills, its own containment and MCP validator, and all seven portable regression suites.

Codex CLI 0.147.0-alpha.6.5 was tested at the component level:

  • all 13 packaged skills appeared from a project-local .agents/skills copy;
  • with freecad-mcp absent from PATH, Codex still loaded and used freecad-engineering and completed the conversation while reporting the MCP startup failure;
  • with freecad-mcp 0.1.20 installed, Codex completed initialization and the read-only list_documents operation against FreeCAD.

Direct import of this root portable bundle through Codex's client-specific marketplace is unverified because that flow currently expects the adapter we chose not to ship. Cursor 3.11.13 is installed on the test machine, but it has no headless agent smoke command, so it is also unverified. Gemini CLI and Antigravity are unverified; Google's participation in Agent Plugins is not evidence that those products load this bundle.

Contributing

This is a fan project, and contributions are welcome. The most useful ones come with a small model or fixture that shows the old behavior, the expected engineering claim, and what evidence supports it. See CONTRIBUTING.md.

License and attribution

Original work in this repository is MIT licensed. Several skills started as vendored snapshots from other MIT projects and retain their own license files and immutable upstream coordinates. See THIRD_PARTY_NOTICES for the details.