Build123d

PyPI version Python CI License: Apache 2.0 build123d-mcp MCP server

An MCP (Model Context Protocol) server that exposes build123d CAD operations as tools, enabling AI assistants to build, inspect, and iterate on 3D geometry interactively.

Why

When using an AI to write build123d scripts, the AI writes blind — it cannot see the geometry it produces. This server closes the feedback loop: the AI can create geometry, render views, query dimensions, and catch errors incrementally rather than writing complete scripts and hoping they are correct.

Tools

Core

• execute — run build123d Python code in a persistent session; use show(shape, name) to register named parts
• reset — clear session back to empty state (namespace, shapes, snapshots)

Geometry inspection

• measure — full geometric summary: volume, area, topology, bounding box, centre of mass, inertia tensor, face-type inventory
• clearance — minimum distance (mm) between two named shapes
• cross_sections — cross-sectional areas at evenly spaced planes along X/Y/Z; useful for detecting voids and wall-thickness variation
• session_state — full JSON snapshot of active shapes, named objects, snapshot names, and Python namespace variables
• last_error — details of the last failed execute(): type, message, line number, and code excerpt

Viewing

• render_view — render one or more shapes as PNG or SVG; supports assembly compositing, high-quality tessellation, and cross-section clip planes

Import / export

• export — export as STEP, STL, or both in one call; targets a named object, the current shape, or * for all objects as an assembly
• import_cad_file — load a STEP or STL file as a named object for comparison

Comparison

• shape_compare — compare two named shapes by volume, bbox, topology, and centre offset
• interference — check intersection volume between two named shapes

Session checkpoints

• save_snapshot / restore_snapshot / diff_snapshot — checkpoint, recover, and compare geometric state

Part library (requires --library flag)

• search_library — search the part library by keyword; returns full parameter specs
• load_part — load a named part with optional parameter overrides

Utility

• version — return the server version
• health_check — verify VTK/SVG/STEP/STL dependencies work end-to-end
• repair_hints — get targeted fix suggestions for a given execute() error message
• workflow_hints — guidance on using the tools effectively

Resources

Read-only MCP resources available to LLM clients:

• build123d://quickref — build123d API quick reference (primitives, booleans, positioning, selectors, fillets)
• build123d://session — live session state as JSON (current shape, named objects, snapshots, variables)
• build123d://bd_warehouse — catalogue of pre-built parametric parts from bd_warehouse (bearings, fasteners, gears, pipes, threads, and more)

Prompts

• start-cad-session — primes a new CAD design session with the task description and step-by-step workflow reminders

See llms.md for full tool reference and usage patterns.

Requirements

• uv
• An MCP-compatible client (Claude Code, Claude Desktop, Cursor, etc.)

All Python dependencies (build123d, vtk, etc.) are installed automatically by uv.

Installation

No clone needed. Install directly from PyPI:

pip install build123d-mcp

Or just use uv tool run — it fetches and runs the package in one step with no prior install required (see below).

---

Adding to MCP clients

The server runs over stdio — the client launches it as a subprocess using uv tool run build123d-mcp.

Note on Python version. All examples below pass --python 3.12. VTK and cadquery-ocp do not yet ship wheels for Python 3.13+, so pinning to 3.12 is required. uv will auto-download a managed Python 3.12 if you don't already have one.

Claude Code

Add to your project's .mcp.json (or ~/.claude/mcp.json for global use):

{
  "mcpServers": {
    "build123d-mcp": {
      "command": "uv",
      "args": ["tool", "run", "--python", "3.12", "build123d-mcp"]
    }
  }
}

Restart Claude Code after editing. The tools appear automatically once connected.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "build123d-mcp": {
      "command": "uv",
      "args": ["tool", "run", "--python", "3.12", "build123d-mcp"]
    }
  }
}

Restart Claude Desktop after saving.

Cursor

Open Settings → MCP and add a new server entry, or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "build123d-mcp": {
      "command": "uv",
      "args": ["tool", "run", "--python", "3.12", "build123d-mcp"]
    }
  }
}

VS Code (GitHub Copilot / Continue)

For Continue extension, add to .continue/config.json:

{
  "mcpServers": [
    {
      "name": "build123d-mcp",
      "command": "uv",
      "args": ["tool", "run", "--python", "3.12", "build123d-mcp"]
    }
  ]
}

For GitHub Copilot with MCP support, add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "build123d-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["tool", "run", "--python", "3.12", "build123d-mcp"]
    }
  }
}

---

System prompt

For best results, paste the contents of default_prompt.md as a system prompt in your AI client. This tells the assistant to work incrementally, verify geometry after each step, and use the tools in the right order.

---

Status

Active development (v0.3.13).