build123d MCP
AI-driven 3D CAD via build123d: execute, render, measure, and export geometry interactively.
Ask AI about build123d MCP
Powered by Claude Β· Grounded in docs
I know everything about build123d MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
build123d-mcp
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; useshow(shape, name)to register named partsresetβ 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 inventoryclearanceβ minimum distance (mm) between two named shapescross_sectionsβ cross-sectional areas at evenly spaced planes along X/Y/Z; useful for detecting voids and wall-thickness variationsession_stateβ full JSON snapshot of active shapes, named objects, snapshot names, and Python namespace variableslast_errorβ details of the last failedexecute(): 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, cross-section clip planes, and optional labels for named shapes or specific faces/edges
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 assemblyimport_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 offsetinterferenceβ 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 specsload_partβ load a named part with optional parameter overrides
Utility
versionβ return the server versionhealth_checkβ verify VTK/SVG/STEP/STL dependencies work end-to-endrepair_hintsβ get targeted fix suggestions for a givenexecute()error messageworkflow_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://selectorsβ task-indexed selector cookbook (get the top face, find circular edges, filter by area/length/radius,Select.LASTin builder context, fillet detection)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)
build123d version: examples in
quickrefandselectorsare tested against build123d 0.10.x (soft-pinned inpyproject.tomlas>=0.10,<0.11). The exact installed version is reported at the top of each resource. If you need a different build123d version, override the dependency and verify the examples still match the API.
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.
Recommended workflow
Build complexity falls into two tiers and the right approach differs between them.
Simple shapes (a few primitives, up to ~5 booleans): build entirely in execute().
Complex shapes (IsoThread, multi-body fillets, high face counts): the execute() timeout (default 120 s) is a hard ceiling. The efficient pattern is:
- Probe in the MCP β small
execute()calls to discover API signatures, size strings, and face counts. Usedir()andimport inspect; inspect.signature(ClassName)freely. - Build in a Python script β run it with Bash (or your shell). No timeout, full Python.
- Import and verify in the MCP:
import_cad_file("/path/to/part.step", "part") measure("part") # verify volume, topology, bounding box render_view(objects="part") # visualise
Timeout note: the default is 120 s. Raise it with
--exec-timeout NorBUILD123D_EXEC_TIMEOUT=N. When a timeout fires, all session state is lost (worker is restarted) β you must re-run any setup code.
Import note: after
import_cad_file()the shape is a named session object. Always render it by name (objects="part") when other shapes from the same build are also in session β two co-located shapes cause Z-fighting (striped colour artifacts). STL imports produce a shell (volume = 0);render_viewandmeasurework, butinterference()and boolean operations require a solid.
bd_warehouse fasteners
bd_warehouse is a full fastener system, not just a thread library. Always:
- Probe sizes first (correct string format is
"M6-1"not"M6-1.0"):from bd_warehouse.fastener import CounterSunkScrew print(CounterSunkScrew.sizes("iso10642")) - Instantiate the fastener object, then pass it to the hole operation β never compute head geometry or tap-drill diameters manually:
from bd_warehouse.fastener import CounterSunkScrew, CounterSinkHole, TapHole screw = CounterSunkScrew(size="M6-1", fastener_type="iso10642", length=10) with BuildPart() as wheel: Cylinder(radius=20, height=10) CounterSinkHole(fastener=screw, depth=10) # countersunk through-hole TapHole(fastener=screw, depth=8) # tapped bore
See build123d://bd_warehouse (MCP resource) for the full catalogue and usage patterns.
Security
Unlike CAD MCP servers that simply exec() user code, build123d-mcp ships with defence-in-depth sandboxing so the server is reasonable to expose to LLM-generated and untrusted prompts. Three layers, all applied before user code runs:
- AST inspection β rejects imports of anything outside the allowlist (
build123d,bd_warehouse,math,numpy,inspect, plus the rest of the safe stdlib subset and a curated set of geometric OCP submodules), blockseval/exec/compile/open, and refuses dunder attribute access (the most common Python sandbox-escape route). - Restricted builtins β the
__builtins__exposed to user code has the dangerous functions removed and__import__rewrapped to enforce the same allowlist at runtime, so a payload that bypasses the AST check still hits the wall on import. - Execution timeout β wall-clock limit (default 120 s,
--exec-timeout Nto override) enforced via SIGALRM, with the worker process restarted on breach so a hung script can't hold the session forever.
Filesystem I/O modules (os, pathlib, shutil), networking (socket, urllib, requests), shell access (subprocess), and the OCP file-I/O submodules (STEPControl, IGESControl, OSD, β¦) are all blocked. Path traversal is rejected for export() and render_view(save_to=).
This is not a perfect sandbox β memory exhaustion isn't bounded, and Python introspection chains via build123d internals could in principle escape β but it raises the bar significantly against realistic prompt-injection payloads.
Extending or relaxing the sandbox
Two CLI flags let you adjust the import policy without giving up the rest of the layers:
--allow-imports scipy,pandasβ extend the allowlist with named modules. Each entry permits the named root and all its submodules. Use for CAD scripts that need extra packages.--allow-all-importsβ disable the import allowlist entirely. The other layers (restricted builtins foropen/eval/etc, exec timeout, dunder-attribute block) still apply. Use only in trusted environments or under OS-level isolation (see below).
Both flags also accept their values via env var (BUILD123D_ALLOW_IMPORTS, BUILD123D_ALLOW_ALL_IMPORTS).
Stronger isolation: OS-level sandboxing
For deployments that need stronger guarantees than Python-level checks (e.g. exposing the server to truly untrusted input, or running with --allow-all-imports), wrap the whole MCP server in an OS-level sandbox:
@anthropic-ai/sandbox-runtimeβ Anthropic's official sandbox runtime, designed exactly for this. The Claude Code docs explicitly call out wrapping MCP servers:npx @anthropic-ai/sandbox-runtime <command-to-sandbox>.- Docker / containers β generic approach; many community MCP-sandbox wrappers exist (e.g.
pottekkat/sandbox-mcp,Automata-Labs-team/code-sandbox-mcp). Run build123d-mcp inside a minimal container with no host filesystem mounts and no network egress. - Claude Code's sandbox (
/sandboxcommand, macOS Seatbelt or Linux bubblewrap) β if you're running build123d-mcp under Claude Code, the host's sandbox already restricts what subprocesses can touch. - Cursor / IDE dev containers β Cursor doesn't ship MCP-specific sandboxing, but you can run the server inside a dev container that the IDE attaches to.
Inside any of these, --allow-all-imports becomes a reasonable default: the OS-level isolation handles the security, and the Python-level allowlist becomes redundant friction. The recommended high-security recipe is sandbox-runtime (or a container) + --allow-all-imports + a strict exec timeout.
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.14).
