FreeCAD Tool Server

An HTTP + MCP tool server that lets an AI agent of your choice drive FreeCAD programmatically — building, analyzing, and exporting real 3D CAD geometry through typed tool calls.

Agents call REST endpoints (or MCP tools) to create primitives, run boolean operations, loft airfoils, drill holes, fillet edges, check clearances, run finite-element analysis via Elmer, and export validated STEP files — receiving structured feedback at every step.

Your agent (Claude Code, Claude Desktop, any MCP/HTTP client)
      │  MCP tools  or  JSON over HTTP
      ▼
FreeCAD Tool Server  (main.py, typed models in models.py)
      │  in-process import
      ▼
FreeCAD 1.1 bundled Python  ──►  OpenCASCADE geometry kernel

The server runs inside FreeCAD's bundled Python interpreter — FreeCAD is imported as a module, not shelled out as a subprocess. That's why you launch it with FreeCAD's python.exe, not your system Python.

---

Prerequisites

• FreeCAD 1.1+ installed (ships its own Python 3.11).
• (Optional, for FEM) Elmer and Gmsh on your PATH for the /fem/* endpoints and elmer_*.py runners.

No system Python is required to run the server — FreeCAD's interpreter provides everything.

---

Setup

1. Install the Python dependencies into FreeCAD's interpreter

Windows

"C:\Program Files\FreeCAD 1.1\bin\python.exe" -m pip install -r requirements.txt

Linux / macOS (adjust to your FreeCAD install)

/path/to/FreeCAD/bin/python -m pip install -r requirements.txt

2. Start the server

Windows — edit the FreeCAD path in start.bat if needed, then:

start.bat

Linux / macOS — set FREECAD_PYTHON to your FreeCAD interpreter, then:

FREECAD_PYTHON=/path/to/FreeCAD/bin/python ./start.sh

The server listens on http://localhost:8000. Interactive API docs (Swagger UI) are at http://localhost:8000/docs.

3. Health check

curl http://localhost:8000/health
# {"status":"ok","freecad_available":true,"freecad_version":"1.1.1",...}

---

Connect your agent

Option A — MCP (Claude Code, Claude Desktop, any MCP client)

mcp_server.py exposes the tool server over the Model Context Protocol. Point your MCP client at it. For Claude Code, add it to your MCP config:

claude mcp add freecad -- "C:\Program Files\FreeCAD 1.1\bin\python.exe" /path/to/mcp_server.py

or add an entry to your client's MCP settings JSON:

{
  "mcpServers": {
    "freecad": {
      "command": "C:\\Program Files\\FreeCAD 1.1\\bin\\python.exe",
      "args": ["/absolute/path/to/mcp_server.py"]
    }
  }
}

The agent then gets every FreeCAD tool as a native MCP tool.

Option B — Claude Code reading AGENTS.md / CLAUDE.md directly

Clone this repo and open it in Claude Code (or any agent that reads AGENTS.md). The bundled AGENTS.md is a complete operating manual — the modeling loop, every endpoint, the common pitfalls, and the required integration checks. Start the server, tell your agent what to build, and it drives the HTTP API using that guide. A copy is provided as CLAUDE.md so Claude Code loads it automatically.

Option C — Raw HTTP from any language

Every tool is a plain REST endpoint. Minimal stdlib Python client (no extra deps) in tools/freecad_client.py:

from tools.freecad_client import FreeCADClient

fc = FreeCADClient()   # defaults to http://127.0.0.1:8000
fc.tool("POST", "/document/create", name="demo")
fc.tool("POST", "/shapes/add_box", name="b", length=50, width=30, height=10)
info = fc.tool("POST", "/model/get_shape_info", shape_name="b")
print(info["volume_mm3"])   # 15000.0

---

The core modeling loop

create_document
  → add primitives (add_box / add_cylinder / add_cone / add_wing)
  → boolean ops (boolean_union / boolean_cut / make_hole)
  → inspect (get_shape_info / bounding_box / check_interference)
  → finish (fillet_edges / chamfer_edges)
  → export (export_step)
  → validate (validate_step)   ← aim for is_clean == true, solid_count == 1

See AGENTS.md for the full endpoint reference, edge-selector rules, the in-place boolean-update pattern, and the mechanical integration checks (interference / clearance) that catch spatial errors before export.

---

Finite-element analysis (optional)

With Elmer and Gmsh installed, the /fem/* endpoints and the elmer_*.py runners cover a broad tutorial set — elasticity, heat, electrostatics, magnetostatics, fluid flow, eigenmodes, and more. These are heavier and require the external Elmer/Gmsh toolchain; the CAD tools work without them.

---

Repository layout

Path	What it is
main.py	FastAPI tool server — all HTTP endpoints
session.py	FreeCAD session logic (geometry, booleans, export, FEM)
models.py	Typed Pydantic request/response models
mcp_server.py	MCP bridge — exposes the tools to MCP clients
freecad_bridge.py	Headless FreeCAD discovery/import helper
AGENTS.md / CLAUDE.md	Agent operating manual (identical content)
elmer_*.py	Standalone Elmer FEM tutorial runners
tools/	Client helper, test suite, integration-check hook, example scripts
start.bat / start.sh	Launchers (use FreeCAD's bundled Python)

---

License

MIT.