Build a Claude CAD tool with MCP

# /// script
# requires-python = ">=3.10,<3.14"
# dependencies = ["mcp>=2,<3", "build123d>=0.13"]
# ///
"""cad_server.py: an MCP server that gives Claude a CAD kernel (build123d) and a DFM checker."""
import re
from math import pi
from pathlib import Path
from typing import Annotated, Any, Literal

from build123d import Axis, Box, Cylinder, GeomType, Pos, export_step as write_step
from mcp.server.mcpserver import MCPServer             # mcp 2.x; on SDK 1.10 to 1.28 this class was FastMCP in mcp.server.fastmcp
from mcp.server.mcpserver.exceptions import ToolError  # the one exception whose text reaches the model
from pydantic import Field

mcp = MCPServer("cad")
OUT_DIR = Path.home() / "cad-out"  # the only folder this server writes to
MIN_WALL = 1.5       # mm: thinnest wall or ligament we will machine (6061, 3-axis mill)
HOLE_EDGE = 1.0      # fastener holes: rim to part edge, in hole diameters (centre to edge 1.5 d)
FASTENER_MAX = 14.0  # mm: bigger openings are cut-outs and only need MIN_WALL
MIN_FILLET = 0.5     # mm: smaller radii need a cutter we do not stock
Dim = Annotated[float, Field(gt=0, le=500)]  # a size in mm; the limits appear in the tool schema
PARTS: dict = {}     # name -> build123d Part; this dict is the server's memory


def get(name: str):
    if name not in PARTS:
        raise ToolError(f"No part named {name!r}. Existing parts: {sorted(PARTS) or 'none'}")
    return PARTS[name]


def store(name: str, part) -> dict[str, Any]:
    if not re.fullmatch(r"[A-Za-z0-9_-]{1,40}", name):
        raise ToolError("name must be 1 to 40 letters, digits, hyphens or underscores")
    PARTS[name] = part
    size = part.bounding_box().size
    return {"name": name, "size_mm": [round(v, 2) for v in (size.X, size.Y, size.Z)],
            "volume_mm3": round(part.volume), "faces": len(part.faces()), "edges": len(part.edges())}


@mcp.tool()
def make_box(name: str, length: Dim, width: Dim, height: Dim) -> dict[str, Any]:
    """Create a block centred on the origin (x=length, y=width, z=height), in mm."""
    return store(name, Box(length, width, height))


@mcp.tool()
def make_plate_with_holes(
    name: str, length: Dim, width: Dim,
    thickness: Annotated[float, Field(ge=MIN_WALL, le=50)],
    hole_diameter: Dim, hole_inset: Dim, bore_diameter: Annotated[float, Field(ge=0, le=500)] = 0.0,
) -> dict[str, Any]:
    """Create a plate centred on the origin with four through-holes, each hole_inset mm from
    its two nearest edges (to the hole centre), plus an optional centre bore. In mm."""
    if not hole_diameter / 2 < hole_inset < min(length, width) / 2:
        raise ToolError("hole_inset must keep the whole hole inside the plate")
    plate = Box(length, width, thickness)
    for sx in (-1, 1):
        for sy in (-1, 1):
            at = Pos(sx * (length / 2 - hole_inset), sy * (width / 2 - hole_inset), 0)
            plate -= at * Cylinder(hole_diameter / 2, thickness * 2)
    if bore_diameter:
        if bore_diameter > min(length, width) - 2 * MIN_WALL:
            raise ToolError("bore_diameter leaves less than the minimum wall at the plate edge")
        plate -= Cylinder(bore_diameter / 2, thickness * 2)
    return store(name, plate)


@mcp.tool()
def fillet_edges(name: str, radius: Dim, which: Literal["corners", "top", "bottom"] = "corners") -> dict[str, Any]:
    """Round edges of a plate: the four vertical "corners", or the outer edge loop of the
    "top" or "bottom" face (not the holes). In mm. Fails if the radius cannot fit."""
    part = get(name)
    box = part.bounding_box()
    if which == "corners":
        edges = [e for e in part.edges().filter_by(Axis.Z)
                 if abs(abs(e.center().X) - box.size.X / 2) < 1e-6
                 and abs(abs(e.center().Y) - box.size.Y / 2) < 1e-6]
        limit = min(box.size.X, box.size.Y) / 2
    else:
        face = part.faces().sort_by(Axis.Z)[-1 if which == "top" else 0]
        edges, limit = face.outer_wire().edges(), box.size.Z
    if not edges:
        raise ToolError(f"No {which} edges found. Was this part already filleted?")
    if radius >= limit:
        raise ToolError(f"radius {radius} mm must be below {limit:.2f} mm for {which} edges")
    try:
        return store(name, part.fillet(radius, edges))
    except ValueError as e:  # the kernel's message is readable ("Failed creating a fillet with radius of 20, try a smaller value...")
        raise ToolError(str(e)) from e


@mcp.tool()
def dfm_check(name: str) -> dict[str, Any]:
    """Check a plate against the shop's CNC rules: minimum wall 1.5 mm, fastener-hole rim at
    least one diameter from the edge, fillet radius at least 0.5 mm. Returns pass, one message
    per violated rule, and the measured values so the design can be corrected."""
    part = get(name)
    top = part.faces().sort_by(Axis.Z)[-1]
    outline, holes = top.outer_wire(), list(top.inner_wires())
    size = part.bounding_box().size
    wall = min(size.X, size.Y, size.Z)  # the smallest bounding-box dimension is the first candidate for thinnest wall
    fasteners = []                     # (rim-to-edge gap, diameter) of each fastener-sized hole
    for i, hole in enumerate(holes):
        gap = hole.distance_to(outline)
        wall = min(wall, gap, *(hole.distance_to(other) for other in holes[i + 1:]))
        if (diameter := hole.bounding_box().size.X) <= FASTENER_MAX:
            fasteners.append((gap, diameter))
    problems = []
    if wall < MIN_WALL:
        problems.append(f"min_wall: thinnest wall is {wall:.2f} mm, needs >= {MIN_WALL} mm")
    tight = [(gap, d) for gap, d in fasteners if gap < HOLE_EDGE * d]
    if tight:
        gap, d = min(tight)
        problems.append(f"hole_to_edge: {len(tight)} hole(s) too close to the edge; worst is {gap:.2f} mm "
                        f"from a {d:.2f} mm hole, needs >= {HOLE_EDGE * d:.2f} mm")
    arcs = [e for e in part.edges().filter_by(GeomType.CIRCLE) if e.length < 2 * pi * e.radius - 1e-6]
    if any(e.radius < MIN_FILLET for e in arcs):
        problems.append(f"fillet: a radius below {MIN_FILLET} mm cannot be cut with our tooling")
    nearest = round(min(gap for gap, _ in fasteners), 2) if fasteners else None
    return {"pass": not problems, "violations": problems,
            "measured": {"min_wall_mm": round(wall, 2), "min_hole_to_edge_mm": nearest, "holes": len(holes)}}


@mcp.tool()
def export_step(name: str) -> dict[str, Any]:
    """Write the part to ~/cad-out/<name>.step. Refuses unless dfm_check passes."""
    part = get(name)
    report = dfm_check(name)
    if not report["pass"]:
        raise ToolError("Refusing to export; dfm_check failed: " + "; ".join(report["violations"]))
    OUT_DIR.mkdir(exist_ok=True)
    path = OUT_DIR / f"{name}.step"
    write_step(part, str(path))
    return {"path": str(path), "checked": True}


if __name__ == "__main__":
    mcp.run()  # stdio transport: Claude Desktop starts this script and talks over stdin/stdout

{
  "mcpServers": {
    "cad": {
      "command": "/opt/homebrew/bin/uv",
      "args": ["run", "/Users/you/cad-mcp/cad_server.py"]
    }
  }
}

{
  "mcpServers": {
    "cad": {
      "command": "/Users/you/cad-mcp/.venv/bin/python",
      "args": ["/Users/you/cad-mcp/cad_server.py"]
    }
  }
}

# one-time: install uv, then find its absolute path for the config file
brew install uv
which uv                                    # for example /opt/homebrew/bin/uv

# try the server without Claude: the MCP Inspector lists tools and lets you call them
npx @modelcontextprotocol/inspector uv run ~/cad-mcp/cad_server.py

# if the server misbehaves inside Claude Desktop, read its log
tail -n 40 ~/Library/Logs/Claude/mcp-server-cad.log

You: Design a mounting plate for a NEMA 17 stepper: 42 x 42 mm, 6 mm aluminium,
     four M3 holes on a 31 mm square, a 22.5 mm pilot bore and nicely rounded
     corners (8 mm). Check it for manufacturability and export STEP.

Claude: I'll build the plate, round the corners, then check it before exporting.
  > make_plate_with_holes(name="mount", length=42, width=42, thickness=6,
                          hole_diameter=3.4, hole_inset=5.5, bore_diameter=22.5)
    {"size_mm": [42.0, 42.0, 6.0], "volume_mm3": 7980, "faces": 11, "edges": 27}
  > fillet_edges(name="mount", radius=8, which="corners")
    {"volume_mm3": 7651, "faces": 15, "edges": 39}
  > dfm_check(name="mount")
    {"pass": false, "violations": ["hole_to_edge: 4 hole(s) too close to the edge;
      worst is 2.76 mm from a 3.40 mm hole, needs >= 3.40 mm"],
     "measured": {"min_wall_mm": 2.76, "min_hole_to_edge_mm": 2.76, "holes": 5}}

Claude: The 8 mm corner radius is larger than the 5.5 mm hole inset, so the rounded
        corner passes closer to the holes than the straight edge. I'll rebuild with 4 mm.
  > make_plate_with_holes(...same arguments...)
  > fillet_edges(name="mount", radius=4, which="corners")
  > dfm_check(name="mount")
    {"pass": true, "violations": [],
     "measured": {"min_wall_mm": 3.8, "min_hole_to_edge_mm": 3.8, "holes": 5}}
  > export_step(name="mount")
    {"path": "/Users/you/cad-out/mount.step", "checked": true}

Claude: Done. mount.step is 42 x 42 x 6 mm with four 3.4 mm holes on a 31 mm square and a
        22.5 mm bore. I reduced the corner radius from 8 mm to 4 mm because at 8 mm the
        holes were only 2.76 mm from the edge, under the 3.4 mm rule.

from build123d import export_stl

@mcp.tool()
def preview(name: str) -> dict[str, Any]:
    """Tessellate a part to STL so Blender or a viewer can show it. Returns the path."""
    path = OUT_DIR / f"{name}.stl"
    OUT_DIR.mkdir(exist_ok=True)
    export_stl(get(name), str(path))                 # B-rep to triangles, for looking only
    return {"path": str(path)}

# test_cad_server.py   run:  uv run --with pytest --with "mcp>=2,<3" --with build123d pytest -q
import pytest
from mcp.server.mcpserver.exceptions import ToolError

import cad_server as cad


def test_good_mount_passes_and_exports(tmp_path, monkeypatch):
    monkeypatch.setattr(cad, "OUT_DIR", tmp_path)
    cad.make_plate_with_holes("t", 50, 50, 6, 3.4, 9.5, 22.5)
    cad.fillet_edges("t", 4)
    assert cad.dfm_check("t")["pass"]
    cad.export_step("t")
    assert (tmp_path / "t.step").exists()


def test_known_bad_design_must_fail():
    cad.make_plate_with_holes("bad", 42, 42, 6, 3.4, 5.5, 22.5)
    cad.fillet_edges("bad", 8)                      # R8 pulls the outline toward the holes
    report = cad.dfm_check("bad")
    assert not report["pass"] and "hole_to_edge" in report["violations"][0]


def test_export_refuses_a_thin_part(tmp_path, monkeypatch):
    monkeypatch.setattr(cad, "OUT_DIR", tmp_path)
    for size in [(40, 40, 1.0), (1.0, 40, 40), (40, 1.0, 40)]:   # a 1 mm wall in z, in x and in y
        cad.make_box("thin", *size)                              # below the 1.5 mm rule
        with pytest.raises(ToolError):
            cad.export_step("thin")
    assert not list(tmp_path.iterdir())