build123d-mcp

Exposes build123d CAD operations as MCP tools so AI assistants can build, inspect, and iterate on 3D geometry interactively.

Unverified

stdio (local)

No auth

Python

View repo 25

Add to your client

Copy the config for your MCP client and paste it into its config file.

Install / run

pip install build123d-mcp

Paste into ~/Library/Application Support/Claude/claude_desktop_config.json

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

Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf

Before you start

uv (astral-sh/uv) — used to fetch and launch the server
An MCP-compatible client (Claude Code, Claude Desktop, Cursor, VS Code/Continue/Copilot, etc.)
Python 3.11, 3.12, 3.13, or 3.14 (uv can auto-download a managed interpreter)
All Python deps (build123d, vtk, etc.) are installed automatically by uv

About build123d-mcp

An MCP server that exposes build123d CAD operations as tools, enabling AI assistants to build, inspect, and iterate on 3D geometry interactively. When an AI writes build123d scripts blind it cannot see the geometry it produces; this server closes the feedback loop so the AI can create geometry, render views, query dimensions, run feature recognition and printability analysis, generate engineering drawings, and catch errors incrementally rather than writing a whole script and hoping it is correct. It runs over stdio (one isolated session per client process), is installed from PyPI, and launched via uv tool run. A persistent execute() session, MCP resources (build123d quick reference, selector cookbook, drafting cookbook, live session state, bd_warehouse parts catalogue), and a start-cad-session prompt round out the workflow.

Tools & capabilities (34)

execute

Run build123d Python code in a persistent session; use show(shape, name) to register named parts.

reset

Clear the session back to empty state (namespace, shapes, snapshots).

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.

resolve

Evaluate a selector expression (e.g. .faces().filter_by(Axis.Z).last()) against a named object and return a geometry descriptor.

find_holes

Feature recognition: coaxial drill + counterbore + spotface stacks reported as one hole record (axis, location, diameter, depth, bottom type).

find_bosses

Feature recognition: external bosses with height.

find_hole_patterns

Recognise bolt-circle and linear-array hole patterns.

analyze_printability

BREP-exact FDM printability analysis: overhangs, thin walls, minimum features, bed fit, tip-over risk.

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.

render_view

Render one or more shapes as PNG/SVG/DXF; auto-detects 3D vs 2D, supports assembly compositing, high-quality tessellation, cross-section clip planes, and optional labels.

suggest_view_layout

Auto-calculate safe page positions for a standard multi-view drawing layout.

view_axes

World-to-page axis mapping for a projected view, computed analytically before rendering.

render_drawing

Rasterise an SVG file from disk to PNG.

inspect_drawing

Structured bbox/annotation report for a 2D drawing (session objects or an SVG on disk).

lint_drawing

Structural drawing-quality checks: label/geometry divergence, overlapping annotations, page overshoot.

save_drawing_annotations

Write a .dims.json sidecar capturing label metadata alongside an exported SVG.

export

Export as STEP / STL / DXF / SVG (or comma-separated); auto-detects 2D vs 3D; 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.

shape_compare

Compare two named shapes by volume, bbox, topology, and centre offset, plus a localized surface-deviation diff pinpointing where geometry changed, with an exact-boolean magnitude.

align_check

Check alignment between two named objects along an axis (flush / center / clearance modes).

save_snapshot

Checkpoint the current geometric state.

restore_snapshot

Recover a previously saved geometric state.

diff_snapshot

Compare geometric state against a snapshot.

search_library

Search the part library by keyword; returns full parameter specs (requires --library flag).

load_part

Load a named part with optional parameter overrides (requires --library flag).

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.

script

Assemble a reproducible Python script from the session's executed code blocks.

install_skill

Copy a b123d workflow skill (modeling or drawing) into the current project (targets: agents-md, claude, cursor, windsurf).

When to use it

Let an AI assistant model 3D parts in build123d with a visual/geometric feedback loop instead of writing scripts blind
Render PNG/SVG/DXF views and measure volume, bounding box, and topology to verify a part matches a spec
Run feature recognition (holes, counterbores, bosses, bolt-circle patterns) on imported or generated geometry
Check FDM 3D-printability — overhangs, thin walls, minimum features, bed fit, tip-over risk — before printing
Generate and lint code-first engineering drawings, then export STEP/STL/DXF/SVG
Use bd_warehouse fasteners (screws, threads, gears, bearings) and a parametric part library in CAD workflows

Security notes

Ships with defence-in-depth sandboxing applied before any user code runs: (1) AST inspection that rejects non-allowlisted imports and blocks eval/exec/compile/open and dunder attribute access; (2) restricted builtins with __import__ rewrapped to enforce the allowlist at runtime; (3) a wall-clock exec timeout (default 120s, --exec-timeout N) enforced via SIGALRM with worker restart on breach. Filesystem, networking, and shell modules are blocked, and path traversal is rejected for export()/render_view(save_to=). Not a perfect sandbox (memory is unbounded; introspection chains could in principle escape) — for untrusted input wrap the whole server in an OS-level sandbox (e.g. @anthropic-ai/sandbox-runtime or a container). --allow-imports / --allow-all-imports / --no-sandbox relax the policy and should be used only in trusted/isolated environments. The --library directory is treated as trusted input — point it only at directories you control. HTTP mode shares a single CAD session across all requests unless per-request session middleware is installed; do not expose it to multiple users without that.

build123d-mcp FAQ

How do I add it to Claude Desktop or Cursor?

Add an mcpServers entry with command "uv" and args ["tool", "run", "--python", "3.12", "build123d-mcp@latest"] to the client's config (claude_desktop_config.json, ~/.cursor/mcp.json, or .mcp.json for Claude Code), then restart the client. The server runs over stdio and uv fetches the package on launch; no clone or prior install is required.

Which Python versions are supported?

Python 3.11, 3.12, 3.13, and 3.14 are all supported and CI-tested. The example config passes --python 3.12 as a widely-available default, but you can swap in any supported interpreter; uv will auto-download a managed Python if you don't have one.

Is it safe to run LLM-generated CAD code?

It ships with defence-in-depth sandboxing (AST import allowlist, restricted builtins with eval/exec/open/__import__ guarded, and a SIGALRM exec timeout); filesystem, network, and shell modules are blocked. It is not a perfect sandbox, so for truly untrusted input the README recommends wrapping the whole server in an OS-level sandbox such as @anthropic-ai/sandbox-runtime or a container.

What is the recommended workflow for complex parts?

Simple shapes can be built entirely in execute(). For complex parts that risk the 120s exec timeout, probe API signatures in the MCP, build the geometry in a standalone Python script (no timeout), then import_cad_file() the result and use measure()/render_view() to verify.

Does it support HTTP transport?

Yes, with --transport http it serves streamable-HTTP for web/embedded deployments, but HTTP mode shares one CAD session across all requests unless per-request session middleware is installed, so it should not be exposed to multiple users without that middleware. The default and recommended transport is stdio.

#cad #build123d #3d-modeling #step #stl #engineering-drawings #fdm #3d-printing #python #stdio

Alternatives to build123d-mcp

Compare all alternatives →

BlenderMCP

Design & Media

23k

Control Blender from Claude and other LLMs for prompt-assisted 3D modeling, scene creation, and asset generation.

Unverified

stdio (local)

No auth

Python

22 tools

Updated 16 days agoRepo

Figma Context MCP (figma-developer-mcp)

Design & Media

15k

Popular community server that feeds Figma layout data to coding agents via a Figma API token.

Verified

stdio (local)

API key

TypeScript

2 tools

Updated 1 month agoRepo

21st.dev Magic MCP

Design & Media

5.2k

Generate beautiful, modern UI components from natural-language descriptions inside your IDE.

Unverified

stdio (local)

API key

TypeScript

4 tools

Updated 4 months agoRepo

Compare build123d-mcp with:

vs BlenderMCP vs Figma Context MCP (figma-developer-mcp)vs 21st.dev Magic MCP vs Shadcn UI v4 MCP Server