_  _                     _
  __ _ (_)| |_   ___   __ _   __| |
 / _` || || __| / __| / _` | / _` |
| (_| || || |_ | (__ | (_| || (_| |
 \__, ||_| \__| \___| \__,_| \__,_|
 |___/

$ pip install gitcad          # mech + ecad + MCP server + exact kernel (v0.9.9)

docs · github.com/gitcad-xyz/gitcad · Apache-2.0

start

There is no application to open. gitcad is an MCP server — you wire it into the agent you already use, once, and from then on you design by asking. Installing the package is only half of it; the agent has to be told the server exists.

$ pip install gitcad
$ claude mcp add gitcad -- gitcad-mcp     # Claude Code

Any other MCP client (Claude Desktop, Cursor, Zed, Codex) takes the same server in its own config file:

{ "mcpServers": { "gitcad": { "command": "gitcad-mcp" } } }

Then say what you want built. The agent's first call is get_started, which scans the working directory and hands back what is already there and what to do next — so a cold session knows where it is without being told:

you   "design a 72 mm floating crankbait — no electronics"

      get_started    what's in this directory, what to do next
      model_new      a project is a repo; the model is text
      viewer_open    ONE URL, opens your browser, outlives the session
      feature_add    build → model_validate → model_measure → export

67 tools, mechanical and electrical. The agent is expected to open the viewer early and leave it up, so you watch the design take shape rather than waiting for a report.

what

A CAD platform where the primary interface is an MCP tool surface, not a GUI. Models are canonical text — geometry (STEP, Gerbers, PDFs) is a build artifact, never source. So designs branch, merge, diff, blame, and release like code, and agents model by verifying — every operation returns machine-readable validation and measurement — instead of hoping.

why

• agents are users. One API for humans, agents, and the web UI. Failures are fingerprinted and auto-reduced to minimal synthetic repros on your machine — your geometry never leaves without your approval.
• git is the backbone. No proprietary vault, no subscription wall around collaboration. Branching and merging work because the source is deterministic text with stable entity identity designed in from day one.
• two domains, one part standard. Mechanical and electrical parts publish the same interface — envelope, frames, typed ports. The enclosure and the PCB live in one history; compatibility is interface-semver, machine-checked.

how

m = model_new()
m = feature_add(m, op="box",      params={dx:60, dy:40, dz:8})
m = feature_add(m, op="cylinder", params={radius:3.2, height:8})
m = feature_add(m, op="boolean",  params={kind:"cut"}, inputs=[...])

model_validate(m)   # watertight? self-intersecting? → structured report
model_measure(m)    # volume, centroid → deterministic oracle

model_export(m, "step")   # → part.step
model_drawing(m)          # → dimensioned drawing on an ISO/ANSI sheet
board_export_fab(b)       # → Gerber X2 + Excellon + pick-and-place

viewer_open(path=".")      # one detached server per project; outlives the session

architecture

Six seams. Everything swappable lives behind one. The kernel is forge — the project's own exact-arithmetic b-rep kernel (the only one; OCCT was removed entirely, ADR-0020). Geometric and topological decisions use exact rationals or certified intervals; an operation the kernel cannot do exactly refuses by name instead of approximating.

Kernel          b-rep ops, validation, measurement   → forgekernel (+ Rust build)
IdentityService stable entity IDs (naming fix)       → lineage-hash
DocumentModel   feature tree ⇄ canonical text        → deterministic JSON
Renderer        headless tessellation → viewer/STL   → forge mesher
DrawingEngine   3D → 2D views, dimensions, sheets    → forge HLR → SVG/PDF
Storage         git models + content-addressed art.  → git

status

• ✓ on PyPI at 0.9.9 — six packages: gitcad, gitcad-core, gitcad-mech, gitcad-ecad, forgekernel, forgekernel_rs; no OCCT anywhere in the dependency tree
• ✓ released kernel capability: 340/345 matrix cells (99%) — 0 gaps; the 5 remaining cells are permanently outside any exact field (each with a transcendence proof) and refuse by name; 0 crashes through the seam
• ✓ 0.9.9 is the field release — driven by the first real bug reports, and named for them. The viewer is now ONE detached server per project: it outlives the agent session (kill the agent; the page keeps serving and live-reloading), opens the browser, always states its URL, and stops only on an explicit viewer_stop. The top assembly is the default view and parts are in-page sub-views (#part= deep links) — never a second server, never a port per part
• ✓ 0.9.9: imports that cannot lie — freeform STEP closure is a polynomial identity in ℚ, never sampled, so a shell that does not close refuses with its gap in millimetres, down to a 1e-9 crack; heal can repair vertex tears and provably cannot paper over a surface crack
• ✓ 0.9.9: every drawing renders on a standard sheet — ISO 5457 A4–A0 and ANSI Y14.1 A–E frames with centring marks and grid references, ISO 7200 title block, standard scale series, correct projection symbol; author, date and revision derive from the part file's git history, and stay blank rather than invented outside a repo
• ✓ the freeform core, from 0.9.8: booleans over NURBS solids (loft × loft end to end) — the volume is a certified interval, a bracket proven to contain the true value, never a bare float; mass_props labels every answer exact or certified ± e. Alongside it: direct editing (move/offset/delete face + exact heal, recorded as replayable intent), molding draft with parting lines, and taper and composite blends

Fixes the field found, in 0.9.9: a union of coplanar-wall lofts crashed raw on 0.9.8 and now refuses by name; patch_flux was silently wrong on B-spline surfaces with interior knots; the planar STEP importer silently chorded curved edges and now refuses; the STEP tokenizer no longer loses entities containing quoted semicolons.

Durable decisions are written as ADRs before code. The rules agents must follow: CLAUDE.md.