build123d-mcp
build123d-mcp
build123dのCAD操作をツールとして公開するMCP(Model Context Protocol)サーバーです。AIアシスタントが3Dジオメトリを対話的に構築、検査、反復できるようにします。
なぜこれが必要か
AIを使ってbuild123dスクリプトを作成する場合、AIは自分が生成するジオメトリを見ることができません。このサーバーはそのフィードバックループを閉じます。AIはスクリプトを完全に書き上げてから正しさを祈るのではなく、ジオメトリの作成、ビューのレンダリング、寸法のクエリ、エラーの検出を段階的に行うことができます。
Related MCP server: 3D MCP Server
ツール
execute— 永続的なセッションでbuild123d Pythonコードを実行します。show(shape, name)を使用して名前付きパーツを登録しますrender_view— 1つ以上の形状をPNGまたはSVGとしてレンダリングします。アセンブリの合成、高品質なテセレーション、断面クリップ平面をサポートしていますmeasure— バウンディングボックス、体積、表面積、トポロジー、最小肉厚、または2つの名前付きボディ間のクリアランスをクエリしますexport— 1回の呼び出しでSTEP、STL、またはその両方としてエクスポートします。名前付きオブジェクトまたは現在の形状を対象としますsession_state— アクティブな形状、名前付きオブジェクト、スナップショット名の完全なJSONスナップショットhealth_check— 作業を開始する前にVTK/SVG/STEP/STLの依存関係が正常に動作するかを確認しますsave_snapshot/restore_snapshot/diff_snapshot— ジオメトリ状態のチェックポイント作成、復元、比較を行いますinterference— 2つの名前付き形状間の交差体積を確認しますlist_objects— ジオメトリ統計を含むすべての名前付き形状をリストしますversion— サーバーのバージョンを返しますreset— セッションを空の状態にリセットします
ツールの詳細なリファレンスと使用パターンについては、llms.mdを参照してください。
要件
MCP互換クライアント(Claude Code、Claude Desktop、Cursorなど)
すべてのPython依存関係(build123d、vtkなど)はuvによって自動的にインストールされます。
インストール
クローンは不要です。PyPIから直接インストールしてください:
pip install build123d-mcpまたは、uv tool runを使用してください。これは事前のインストールなしでパッケージを取得して実行します(下記参照)。
MCPクライアントへの追加
サーバーはstdio経由で実行されます。クライアントはuv tool run build123d-mcpを使用してサブプロセスとして起動します。
Pythonバージョンに関する注意。 以下のすべての例では
--python 3.12を渡しています。VTKおよびcadquery-ocpはまだPython 3.13+用のホイールを提供していないため、3.12に固定する必要があります。まだお持ちでない場合、uvは管理されたPython 3.12を自動的にダウンロードします。
Claude Code
プロジェクトの.mcp.json(またはグローバル使用の場合は~/.claude/mcp.json)に追加します:
{
"mcpServers": {
"build123d-mcp": {
"command": "uv",
"args": ["tool", "run", "--python", "3.12", "build123d-mcp"]
}
}
}編集後、Claude Codeを再起動してください。接続されるとツールが自動的に表示されます。
Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json(macOS)または%APPDATA%\Claude\claude_desktop_config.json(Windows)を編集します:
{
"mcpServers": {
"build123d-mcp": {
"command": "uv",
"args": ["tool", "run", "--python", "3.12", "build123d-mcp"]
}
}
}保存後、Claude Desktopを再起動してください。
Cursor
Settings → MCPを開いて新しいサーバーエントリを追加するか、~/.cursor/mcp.jsonを編集します:
{
"mcpServers": {
"build123d-mcp": {
"command": "uv",
"args": ["tool", "run", "--python", "3.12", "build123d-mcp"]
}
}
}VS Code (GitHub Copilot / Continue)
Continue拡張機能の場合は、.continue/config.jsonに追加します:
{
"mcpServers": [
{
"name": "build123d-mcp",
"command": "uv",
"args": ["tool", "run", "--python", "3.12", "build123d-mcp"]
}
]
}MCPサポート付きのGitHub Copilotの場合は、ワークスペースの.vscode/mcp.jsonに追加します:
{
"servers": {
"build123d-mcp": {
"type": "stdio",
"command": "uv",
"args": ["tool", "run", "--python", "3.12", "build123d-mcp"]
}
}
}システムプロンプト
最良の結果を得るには、default_prompt.mdの内容をAIクライアントのシステムプロンプトとして貼り付けてください。これにより、AIは段階的に作業し、各ステップの後にジオメトリを検証し、適切な順序でツールを使用するようになります。
ステータス
活発に開発中 (v0.1.0)。
Available Tools
48 toolsanalyze_printabilityARead-only
Analyse a build123d shape for FDM printability using augura (BREP-exact analysis).
Checks: overhangs, manifold/watertight, tip-over risk, brim/raft need,
minimum vertical feature (→ max layer height), and thin walls. Optionally
checks bed-fit against a declared build volume.
Returns a plain-text summary followed by a JSON report with per-finding
detail (kind, severity, message, area/location where applicable).
object_name: named object from show() (default: current shape).
support_angle: faces shallower than this many degrees from horizontal need
support (default 45).
nozzle: nozzle diameter in mm for wall-thickness check (default 0.4).
min_perimeters: walls thinner than min_perimeters × nozzle are flagged
(default 2).
build_volume: optional build envelope as 'X Y Z' in mm, e.g. '256 256 256';
omit to skip the bed-fit check.
bed_tol: Z tolerance in mm for identifying bed-contact faces (default 0.001);
raise it for parts whose bottom faces sit slightly off Z=0.
min_feature: minimum vertical feature size in mm to flag (default 0.5).
Inputs: nozzle, bed_tol, min_feature, object_name, +3 more. Returns: result
bank_candidateAIdempotent
Atomically promote a gate-clean STEP as the safe output/checkpoint. Writes the candidate to a private sibling file, runs the authoritative written-and-reimported STEP gate, and replaces filename only on a fully verified PASS; on FAIL or an unchecked mesh gate, the candidate is deleted and any existing output is preserved. If snapshot_name is supplied, the geometry snapshot is saved only after promotion. Returns JSON including banked, preservation/snapshot status, the export report, and the next recommended recognition or repair call. Use this instead of batching export() and save_snapshot() for scored floors and final candidates.
Inputs: filename (required), object_name, snapshot_name. Returns: result
compareARead-only
Unified comparison tool.
kind='shape' compares two named shapes from show(), a and b, by
volume/bbox/topology and localized surface deviation; b is required.
kind='fit' reports the spatial relationship between two named shapes, a and b:
clearance, apart/touching/containing/interpenetrating status, containment,
and overlap volumes; b is required.
kind='align' checks two named shapes, a and b, along one axis. axis: X, Y, or Z.
mode: flush (bbox extreme offset), center (centroid offset), or clearance
(nearest-face gap); b is required.
kind='snapshot' compares snapshot a against the current session state
or b as a second snapshot. format: 'text' or 'json'.
Inputs: a (required), b, axis, kind, +2 more. Returns: result
crop_drawingARead-only
Save one model-selected raster drawing region at readable scale. bbox_px is exact source-image [x0,y0,x1,y1]; scale is 0.25..12. Returns the saved PNG path and an exact crop-pixel→source-pixel transform, so coordinates read from the enlargement remain usable. This is a mechanical crop only: it performs no OCR, feature recognition, or geometry inference.
Inputs: bbox_px (required), image_path (required), scale, output_path, +1 more. Returns: result
cross_sectionsARead-only
Compute cross-sectional areas at evenly spaced planes along an axis. Returns a list of {position, area} pairs. axis: X, Y, or Z (default Z). num_slices: number of planes (default 10, minimum 2). Useful for detecting internal voids, wall-thickness variation, or verifying that a shape's cross-section profile matches a reference. object_name: named object from show() (default: current shape).
Inputs: axis, num_slices, object_name. Returns: result
design_auditARead-only
Audit the current session program as a design, not just a shape: surface its named numeric parameters (Θ) and test how robust each is to editing. Parses the assembled program (see script()) for top-level numeric assignments (e.g. plate_thickness = 5.0), then rebuilds the program with each parameter nudged ±epsilon (default ±10%) in a hard-bounded subprocess (the live session is never mutated) and runs the validity gate on each result. Returns JSON: {parameters, baseline, audit:[{name, value, perturbations:[{delta_pct (realized), new_value, discrete_step?, rebuilt, passes_gate, volume_delta_pct, reasons?}], brittle}], summary:{robust, brittle, inconclusive, ...}, note}. A parameter is brittle if a small change fails to rebuild or drops below the validity gate — the thin-wall / coordinate-reasoning failure mode where a valid shape is not an editable design (Arko-T §6); a parameter reassigned at the top level is inconclusive (perturbation is overwritten), not counted as robust. If no named parameters are found, the program uses inline magic constants and the note advises hoisting them to a parameter block. Known limitation: only literal-valued top-level names are surfaced as Θ — a derived parameter (radius = diameter / 2) is not listed, though perturbing its upstream literal flows through. Bounded by a wall-clock budget and max_params (returns a partial report rather than risking a timeout). epsilon: relative nudge, 0<epsilon<1. max_params: cap on parameters audited.
Inputs: epsilon, max_params. Returns: result
destroy_sessionADestructiveIdempotent
Close THIS client's CAD session, discarding its namespace, objects and snapshots, and release its worker subprocess. The next tool call transparently starts a fresh session under the same handle. Use when abandoning a model entirely; prefer reset() to clear geometry while keeping the session. Only meaningful over HTTP with a session handle configured.
Inputs: no named parameters. Returns: result
edit_featureA
Transactionally resize one plain cylindrical through hole identified by a current @feature handle. Reject holes with counterbores, spotfaces, countersinks or multiple constituent faces. Predict the annular volume change, then check exact added/removed material, hole recognition, every other hole and the outer envelope before registering the result. protected_refs is a JSON list of other hole handles; the target itself cannot be protected. On failure no result is registered. Defaults to replacing the named source; result_name can preserve it under a new name.
Inputs: handle (required), diameter (required), result_name, protected_refs. Returns: result
executeA
Execute build123d Python code in the persistent session. Errors include automatic fix hints — read them before retrying. Use show(shape, name) to register named objects (name defaults to 'shape'); show() immediately prints volume and face count confirming the shape is non-empty. After any boolean operation (-, +, &) call measure() to confirm it succeeded (check topology.faces). named_face(shape, name) is a built-in helper: named_face(box, 'top') returns the highest-Z face, 'bottom'/'front'/'back'/'left'/'right' work similarly. find_edges(shape, geom='circle', radius=4.25, at_z=10.2, length=None, tol=0.05) filters edges for fillet/chamfer selection and prints what matched. Analysis primitives are callable INSIDE this execute() code and return real Python objects so you compose (filter, do arithmetic) instead of copying numbers out of a tool result: measure(shape) -> dict (measure(part)['volume']), clearance(a, b) -> dict, cross_sections(shape) -> list of {position,area}, find_holes(shape) -> hole records with .location (an (x,y,z) tuple), .diameter, .depth, … ([h for h in find_holes(part) if h.location[0] < 5]); find_bosses(shape) / find_bored_bosses(shape) / find_countersinks(shape) / find_hole_patterns(shape) return recogniser records too; align_check(a, b, axis='Z', mode='flush') -> dict (align_check(a,b)['delta'] is a float). For standalone MCP comparison calls, use compare(a='axle', b='frame', kind='fit'), compare(a='a', b='b', kind='align'), compare(a='before', b='after', kind='shape'), or compare(a='before', kind='snapshot'). shape defaults to the current shape, and measure/clearance/cross_sections stay bounded on large shapes. save_json(name, obj) writes structured analysis data (face inventories, hole tables) to a server scratch file and returns its path — use it instead of printing large results; open()/os stay blocked.
Inputs: code (required). Returns: result
execute_fileA
Execute a canonical build123d .py file in a clean namespace and atomically promote its result. The prior active model is restored if the source has a syntax/runtime error, times out, produces no shape, or does not produce result_name. Assign a Shape to result or call show(); optionally set result_name to require/register a specific Shape or BuildPart variable. snapshot saves the promoted geometry checkpoint. Returns source SHA-256 provenance plus captured output. The source must be UTF-8, under an allowed read root, and no larger than BUILD123D_MAX_SCRIPT_BYTES (default 2 MiB). Use this for substantial generation revisions: edit model.py, execute_file(), then validate/measure/render/export through MCP.
Inputs: path (required), snapshot, result_name. Returns: result
exportAIdempotent
Export model. format: step, stl, 3mf, dxf, svg, or comma-separated list e.g. 'step,stl' or 'dxf,svg'. 3D shapes (solids) export to step/stl/3mf; 2D shapes (Sketches and dimensioned drawings composed via build123d.drafting) export to dxf/svg. 3mf is a minimal core-spec mesh export (single object, no color/material) intended for slicers (Bambu Studio, PrusaSlicer, Orca) — use step for downstream CAD interop instead. Mixing 2D and 3D formats for the same shape errors with a clear message. object_name: named object from show(), '' to export all named shapes as a combined assembly (default: current shape). STEP exports carry the session names as labels — single-object exports use the object_name, '' exports produce a Compound labelled 'assembly' with each child labelled by its show() name. Downstream CAD tools (FreeCAD, Fusion) will see the structured assembly with named bodies. Use dxf for engineering-drawing handoff to other CAD tools; svg for embedding in docs/wikis. The result echoes the exported shape's volume/bbox/face count (or bbox/edge count for 2D) as a final sanity check that the right, non-degenerate object was written.
Inputs: filename (required), format, object_name. Returns: result
find_bored_bossesARead-only
Find candidate bored bosses and report target-selection/edit evidence: bore opening location, axis into the part, outward axis, bore diameter/depth, planar cap faces at the opening, whether the cap is split across multiple faces, and construction advice. Use this before lengthening any boss that carries a bore, whatever its outer profile; it is read-only and diagnostic, not proof of the requested target.
Inputs: object_name. Returns: result
find_bossesARead-only
Recognise external cylindrical bosses on a session object (defaults to current shape), including a turned part's OD — filter on diameter against the part envelope for local bosses only. Returns JSON: {count, bosses: [{axis (base toward free end), location (free-end point), diameter, height}]}.
Inputs: object_name. Returns: result
find_candidatesARead-only
List recognised instances of a hole, boss, polygonal boss, slot, chamfer or fillet. qualifiers is JSON with optional axis (X/Y/Z), side (+X/-X/+Y/-Y/+Z/-Z, relative to the part bounding-box centre), and value_field; matches are reported for the literal axes and grouped over all 24 proper rotations of the request frame (no mirror readings, none preferred). stated_value is checked against the measured feature value within 0.1 mm or 1%. An unmatched value is flagged; empty or truncated recognition is never treated as proof of absence. Returns exact @feature handles for recognised instances.
Inputs: kind (required), qualifiers, object_name, stated_value. Returns: result
find_countersinksARead-only
Recognise countersinks (conical screw-head recesses) on a session object (defaults to current shape) — the feature find_holes reports only as a plain opening. A countersink is an internal cone flaring from a drilled bore out to a larger opening, coaxial with the drill; drill-point cones and external edge chamfers are excluded. Returns JSON: {count, countersinks: [{location (opening centre), axis (into the part), major_diameter (countersink Ø at the surface), drill_diameter, included_angle (deg, e.g. 82/90/100/120), depth}]}. object_name: named object from show() (default: current shape).
Inputs: object_name. Returns: result
find_hole_patternsARead-only
Recognise hole patterns on a session object (defaults to current shape): ≥3 identical-spec holes equally spaced on a circle → bolt_circle (center, diameter/BCD), collinear at constant pitch → linear_array (pitch, direction). Returns JSON: {count, patterns: [{type, holes: [HoleFeature records], center/diameter | pitch/direction}]}. Each hole belongs to at most one pattern; make_drawing already annotates these automatically.
Inputs: object_name. Returns: result
find_holesARead-only
Recognise drilled holes on a session object (defaults to current shape). Coaxial internal cylinders are grouped into one record per hole: drill + counterbore + spotface stacks, keyway-split bores, and bores interrupted by crossing holes all count once. Returns JSON: {count, holes: [{axis (drilling direction, unit vector), location (opening point), diameter, depth (bore top to deep end; drill-point cone excluded), bottom: through|flat|drill_point|unknown, cbore: {diameter, depth}|null, spotface: {diameter, depth}|null}]}. Countersinks read as openings (not steps); threads and non-cylindrical features are not recognised.
Inputs: object_name. Returns: result
health_checkARead-only
Verify that render and export dependencies are working. Tests PNG render (VTK), SVG render (build123d HLR), STEP export, and STL export with a trivial shape. Returns JSON with ok/error per capability. Run at session start if you suspect a missing dependency.
Inputs: no named parameters. Returns: result
import_cad_fileA
Import a STEP (.step/.stp), STL (.stl), or 3MF (.3mf) file as a named object in the session. path: absolute or relative path to the file. name: name to register the shape under (defaults to the filename stem). The shape becomes both the named object and the current_shape. A multi-object 3MF registers an aggregate under name plus each member as name_1, name_2, etc.; the result includes per-member topology summaries. After importing, use render_view() to visualise the shape, measure() for geometry queries, or compare(a='imported', b='model', kind='shape') to diff against a show() object. Note: STL imports produce a shell (volume=0) rather than a solid. 3MF commonly yields editable solids when its meshes are closed, but callers must check the returned solids and volume fields rather than assuming every mesh is valid. If you have both the original built shape and an imported copy in session.objects, render the imported one by name (e.g. objects='mypart') to avoid Z-fighting artifacts from two co-located shapes.
Inputs: path (required), name. Returns: result
inspect_drawingARead-only
DEPRECATED (#465) — moved to draftwright; off by default in 0.4.0, removed in 0.5.0. Calling it explains the replacement. Structured bbox and annotation report for a 2D drawing.
Two modes:
1. Session mode (default): inspects objects registered via annotate()/show().
Returns per-object bounding boxes, face/edge counts, annotation metadata
(label string, measured length, Leader tip/elbow), and structural lint.
2. SVG mode (svg_path set): parses an SVG file from disk and reports page
size, layer ids, text content + positions, and element counts. Decouples
inspection from the build-and-register ceremony — works on SVGs from any
source (CI artifacts, third-party exports, prior runs).
Use annotate(result, name) instead of show(result.shape, name) when building
with build123d_drafting so metadata is captured:
from build123d_drafting import Dimension, Draft
draft = Draft(font_size=2.5, decimal_precision=1)
w = Dimension((-20, -10, 0), (20, -10, 0), "below", 8, draft, label="40")
annotate(w, "width_dim")
For vanilla build123d.ExtensionLine/DimensionLine, pass the label explicitly:
w = ExtensionLine(border=[...], offset=6, draft=draft, label="40")
annotate(w, "width_dim", label="40")
Args:
objects: comma-separated object names (default: all). Session mode only.
svg_path: path to an SVG file on disk. Switches to SVG mode.
Inputs: objects, svg_path. Returns: result
inspect_partARead-only
Return one compact generation-checkpoint inventory: bbox, solid/topology counts, holes grouped by axis/diameter/depth/bottom, bosses grouped by axis/diameter/height, recognised patterns with member counts, and a cross-section area profile. expected is an optional JSON object derived from the drawing/spec; supported keys are bbox [x,y,z], solid_count, holes/bosses/patterns group lists, section_varying, and tolerance. Pattern groups can check type, diameter, pitch, direction, center, member_count, and member_diameter. A supplied feature category is an exact inventory: unexpected or ambiguously matched groups fail. With expectations, returns explicit PASS/FAIL plus mismatches. Without them, returns INVENTORY plus heuristic warnings for shallow partial cuts and nearly constant sections. Unsupported expectation keys are rejected; this tool contains no built-in fixture expectations.
Inputs: expected, object_name, section_axis, section_slices. Returns: result
install_skillA
Copy a b123d workflow skill into the current project.
Writes the appropriate config file for the requested agent so the
step-by-step workflow is available in future sessions.
skill: which workflow to install (default "modeling")
- drawing → DEPRECATED; still installs, but drawing generation has moved to
draftwright, which publishes its own skill (#465)
- modeling → build 3D parts/assemblies (incl. from technical drawings)
- edit → modify existing build123d code and verify geometry deltas
- repair → repair a solid that fails the validity gate
target: one of "claude" (default), "agents-md", "cursor", "windsurf"
- claude → .claude/skills/<skill-dir>/SKILL.md (Claude Code)
- agents-md → AGENTS.md (Codex CLI, Antigravity, GitHub Copilot, Cline)
- cursor → .cursor/rules/<skill-dir>.mdc
- windsurf → .windsurfrules
force: overwrite existing installation (default False)
Inputs: force, skill, target. Returns: result
interface_featuresARead-only
Suggest planar mounting faces from recognised hole openings, with exact hole handles. These are geometric candidates, not a declaration of design intent. Pass chosen hole handles as protected_refs to edit_feature(); that edit also checks every other recognised hole and the outer envelope.
Inputs: object_name. Returns: result
last_errorARead-only
Return details of the last failed execute() call: exception type, message, and (for runtime and syntax errors) line number and a 5-line excerpt around the failing line. Security errors include a message but no line/excerpt. Returns {"error": null} if the last execute() succeeded or no execute() has failed yet. Call this immediately after an execute() error to get the exact failing line — much faster than re-reading the submitted code.
Inputs: no named parameters. Returns: result
lint_drawingARead-only
DEPRECATED (#465) — moved to draftwright; off by default in 0.4.0, removed in 0.5.0. Calling it explains the replacement. Run structural drawing-quality checks and return JSON {violations: [...]}.
Session mode (default): reconstructs the session's annotations and delegates
to build123d-drafting-helpers (lint_drawing + find_interferences) — single
source of truth. Surfaces label-vs-measured divergence (axis swap), Leader
line through its own label, annotation/label overlap, a witness/extension
line piercing a neighbour's label, redundant collinear lines, and page-bounds
overshoot.
SVG mode (svg_path set): scans an SVG file for export-only pathologies — most
importantly native <text> elements (build123d renders glyph paths, so any
<text> won't DXF-export and won't scale with the model).
drawing_scale: when the geometry was scaled up before projecting — e.g. a
7.5 mm feature drawn at 5:1 via part.scale(5) — pass the same factor (5.0)
so the label-vs-measured check divides each measured path length by it
before comparing to the label. This lets labels carry the *real* dimension
while the geometry is drawn enlarged, instead of every dim tripping a false
axis-swap warning. Session mode only; defaults to 1.0 (no scaling).
view_shape_names: list of shape names (from show()) representing the placed
view outlines. Used to detect view_annotation_overlap (annotation bbox
overlaps a view outline) and view_overlap (two view outlines overlap).
Pass the visible-side placed compounds from each projection, e.g.
["front_placed", "side_placed", "plan_placed", "iso"]. Session mode only.
Each violation is {severity, check, object, message}. Run this after major
drawing additions; running it BEFORE rendering catches the bug at the source.
Inputs: svg_path, drawing_scale, view_shape_names. Returns: result
list_sessionsARead-only
Report how many CAD sessions this server process is holding, its configured limit, and how long each has been idle. Handles are secrets and are never returned. Operator/diagnostic tool for HTTP deployments — over stdio there is always exactly one session.
Inputs: no named parameters. Returns: result
locate_gate_defectsARead-only
Report WHERE a solid fails the validity gate, with 3D coordinates — so you can fix the exact edge/face instead of guessing. validate()/export() tell you WHAT is wrong (e.g. "1 non-manifold edge", "BRepCheck failed") but not where; call this when validate() FAILs to get a per-defect list: brep_invalid_face (face index + center + BRepCheck status, e.g. an unorientable BSpline), open_edge / nonmanifold_edge (B-rep edge midpoint + faces_incident), the mesh self-touches strict CAD/mesh consumers reject — mesh_nonmanifold_edge (edge midpoint) and mesh_nonmanifold_vertex (corner-to-corner touch point), mesh_untriangulated_face (a face that cannot tessellate at the base tolerance), mesh_refined_untriangulated_face (a face that only fails at a finer tolerance) — and mesh_vertex_deflection_defect (a tessellated edge endpoint that misses its own BREP vertex by more than the mesh deflection — a patched/healed face whose boundary is topologically closed but geometrically off-vertex; BRepCheck and even the open-edge count can both read clean, but a strict mesh sanity check still rejects it). Each defect includes a generic repair hint plus diagnostic_class / repair_family / next_step metadata; the top-level diagnosis block counts defect kinds and recommends the next verification path. An empty list means the part passes the structural checks. Bounded out-of-process (it mesh-checks), so a huge part returns a clean budget error rather than hanging. object_name: named object from show() (default: current shape).
Inputs: object_name. Returns: result
measureARead-only
Measure a shape and return a complete geometric summary: volume (mm³), surface area (mm²), topology (face/edge/vertex counts), bounding box with per-axis size and center, volumetric center of mass, 6-component inertia tensor (Ixx/Iyy/Izz/Ixy/Ixz/Iyz), and a face-type inventory classifying every face as Plane/Cylinder/Cone/Sphere/Torus/BSpline with area and type-specific params (e.g. cylinder diameter and axis); identical faces are collapsed with a count, non-analytic sliver faces folded into one summary line. Prefer measure over render_view for verifying geometry — numbers are unambiguous. topology is the fastest confirmation that a boolean operation succeeded: a failed cut leaves face/edge/vertex counts unchanged. object_name: named object from show() (default: current shape). density (g/cm³) or material preset (steel, stainless, aluminum/6061, brass, copper, titanium, abs, pla, petg, nylon) adds mass_g and scales inertia to true mass moments in g·mm².
Inputs: density, material, object_name. Returns: result
mesh_holesARead-only
Find fastener holes in a MESH by slicing it on all three axes. Returns JSON {count, holes:[{axis, diameter, location, span, depth, through}]} where axis is the drilling direction and location is the hole centre in world coordinates. This is the mesh counterpart to find_holes(), which needs real topology and returns nothing for an imported STL - the usual case when remixing a downloaded model and you need its existing mounting features before designing a part that bolts on. Read depth and through: a blind pocket a few mm deep is a heat-set insert seat, not a screw hole, and coaxial pockets bored into opposite faces are reported separately rather than merged into one false through hole. min_diameter/max_diameter default to M2-M8 clearance, counterbores and insert pockets. min_depth drops chamfer rings and tessellation slivers. It reports what the cross-sections show and does not classify countersinks or thread forms. object_name: named object from show()/import_cad_file (default: current shape).
Inputs: weld, slices, min_depth, tolerance, +3 more. Returns: result
mesh_sectionARead-only
Loops on one cross-section plane of a mesh, largest first. Returns JSON {axis, position, loop_count, enclosed_passages, loops:[{points, center, size, min, max, enclosed}]}, all in the two axes that are not axis. enclosed_passages counts loops at odd nesting depth, representing passages through material at this height. An open groove reads 0. Works on imported STL shells and solids. axis: X, Y or Z (the plane normal). position: absolute world coordinate. tolerance: tessellation tolerance. weld: point-merge distance when chaining segments. object_name: named object from show()/import_cad_file (default: current shape).
Inputs: axis, weld, position, tolerance, +1 more. Returns: result
prepare_drawingARead-only
Prepare a raster engineering drawing for efficient inspection. Detects substantial spatial regions, saves one labelled overview plus readable PNG crops, and returns their pixel bounding boxes and paths. Region ids are layout evidence only: this tool does NOT label views, recognise CAD features, interpret lines, infer dimensions, or trace geometry. Use it once near the start instead of repeatedly writing shell/PIL crop scripts; inspect the returned overview and only the relevant crops. Printed dimensions remain authoritative. image_path: PNG/JPEG/TIFF drawing under an allowed read root. output_dir: crop directory under an allowed write root. max_regions: 1..30. padding: crop padding in pixels, 0..500.
Inputs: image_path (required), padding, output_dir, max_regions. Returns: result
recognise_featuresARead-only
Run the shared quiddity inventory once and return exact, run-local edit evidence. With families='' the response is a compact inventory and targetable-family count; pass comma-separated families such as 'holes,bosses,blends' for structured records and @feature handles. Returned handles are usable inside execute() as recognition_faces(handle), or recognition_faces(handle, role='defining'), and fail if their source geometry has been replaced. coordinate_frame='caller' (default) preserves the imported model coordinates used by edit instructions; 'part' uses a rigid-equivariant part-relative frame and returns that frame. include_faces adds exact caller-face indices and geometry descriptors. max_features limits expanded records to 1..100; counts remain exact.
Inputs: families, object_name, max_features, include_faces, +1 more. Returns: result
render_drawingARead-only
DEPRECATED (#465) — moved to draftwright; off by default in 0.4.0, removed in 0.5.0. Calling it explains the replacement. Rasterise an existing SVG file to PNG via resvg-py.
Complements render_view (which takes build123d shapes from the live
session) by accepting an SVG written outside the sandbox — typically by
a short Python script that does the ExportSVG call directly. The PNG is
returned inline so the LLM can see the drawing without you having to
open the file in another tool.
Args:
svg_path: path to an SVG file on disk.
width: output pixel width (default 1200); height set by SVG aspect ratio.
save_to: optional path to write the PNG. If empty, PNG bytes are
delivered inline only.
Inputs: svg_path (required), width, save_to.
render_viewARead-only
Render model. Auto-detects 3D vs 2D: solids use VTK; flat drawings use the 2D pipeline. Renders confirm appearance, not geometry. format: png, svg, dxf, or both. direction accepts top, bottom, front, rear, side, left, right, or iso. quality: preview, standard, or high; a timed-out standard/high PNG automatically retries once as a coarse preview. azimuth/elevation apply after the preset. objects selects comma-separated registered names. clip_plane: x/y/z. save_to writes the result. mode: auto/2d/3d. label_objects and highlights add PNG labels; colors controls object/layer colours.
Inputs: mode, colors, format, azimuth, +9 more.
repair_adviceARead-only
Return structured, field-proven repair/edit recipes for an agent to implement explicitly in execute(). Unlike repair_hints(), which gives short error-specific tips, this emits a sequenced plan with code-pattern names, acceptance checks, and stop conditions. Provide the full validate()/export()/last_error() text as error_text, the intended edit as goal, and any extra notes from locate_gate_defects()/compare(a='before', b='after', kind='shape') as context. The tool is read-only and does not mutate geometry.
Inputs: goal, context, error_text. Returns: result
repair_hintsARead-only
Given an error message or validity-gate reason, return targeted fix suggestions for common build123d mistakes and gate failures: wrong Location syntax, missing .part, CadQuery idioms, blocked imports, degenerate boolean results, fillet edge selection, B-rep defects, mesh non-manifold/open-edge failures, and more. Pass the full error string from execute(), last_error(), validate(), or export().
Inputs: error_text (required). Returns: result
resetADestructiveIdempotent
Clear the current session back to empty state, including all snapshots.
Inputs: no named parameters. Returns: result
resolveAIdempotent
Evaluate a selector expression against a named object and return a geometry descriptor. selector is a Python expression suffix applied to the object, e.g. '.faces().filter_by(Axis.Z).last()'. If label is given, the descriptor is stored in session.geometry_refs[label] and appears in session_state(). Returns JSON: {label, ref, object, selector, type, geom_type, area/length, center}. center is the entity's true centre — the arc centre for a circular/elliptical edge, the area centroid otherwise — not the parametric midpoint, which for a circle or cylinder lies ON the entity a radius from its axis. A planar face also carries normal; a curved face carries axis {origin, direction} and radius instead, because a curved face has no single normal (a sphere carries neither — its centre and radius say everything). A list-valued selector carries count, an aggregate center averaged over every match, and per-entity descriptors in entities (first 50, with entities_truncated when there are more). The ref field uses @cad[object#label] format.
Inputs: selector (required), object_name (required), label. Returns: result
restore_snapshotAIdempotent
Restore geometric state from a previously saved snapshot (current_shape and the show() registry). The Python variable namespace is NOT restored — execute() calls made after the snapshot are still in scope, but current_shape and all show() objects revert to what they were at snapshot time. Raises an error if the snapshot name does not exist.
Inputs: name (required). Returns: result
save_drawing_annotationsA
DEPRECATED (#465) — moved to draftwright; off by default in 0.4.0, removed in 0.5.0. Calling it explains the replacement. Write a .dims.json sidecar file alongside an SVG with label metadata.
build123d renders Text as filled glyph paths, not <text> SVG elements, so
label strings are irrecoverable from a finished SVG. Call this tool after
completing a drawing (annotate all dims/leaders with annotate()) and before
or after exporting the SVG. The sidecar is read automatically by
inspect_drawing(svg_path=...) to restore annotation content.
Workflow:
1. Build your drawing with Dimension / Leader / annotate()
2. Export SVG: execute("exporter.write('drawing.svg')")
3. Save metadata: save_drawing_annotations("drawing.svg")
4. Inspect later: inspect_drawing(svg_path="drawing.svg")
→ includes full annotations dict from the sidecar
Args:
svg_path: path to the SVG file (sidecar written as <svg_path>.dims.json).
Inputs: svg_path (required). Returns: result
save_snapshotAIdempotent
Save a named checkpoint of the current geometric state (current_shape and the show() object registry). The Python variable namespace is NOT saved — only geometry. Call this before risky experiments so you can restore known-good geometry without re-running all prior execute() calls.
Inputs: name (required). Returns: result
scriptARead-only
Return a single Python script assembled from all successfully executed code blocks in this session. Prepends 'from build123d import *' if not already present. If save_to is given, writes the script to that path and returns {script_path, blocks}; otherwise returns {script, blocks}. Useful for exporting a reproducible script after an interactive session.
Inputs: save_to. Returns: result
session_stateARead-only
Return a structured JSON snapshot of the current session: current_shape metrics, all named objects (replaces list_objects) with geometry stats, snapshot names, and a variables summary of the Python namespace (type + volume for shapes, type + length for collections, type + value for scalars). Use this to orient after a reset, restore, or multi-step build to confirm what geometry and variables are active.
Inputs: no named parameters. Returns: result
suggest_view_layoutARead-only
DEPRECATED (#465) — moved to draftwright; off by default in 0.4.0, removed in 0.5.0. Calling it explains the replacement. Auto-calculate safe VIEW_X / VIEW_Y positions for a multi-view engineering drawing.
Measures the named shape's bounding box and returns per-view page positions
(VIEW_X, VIEW_Y), look_at values, and camera/up vectors for a standard
third-angle layout:
[plan ] [ ]
[front] [ side ] [ iso ]
[ title block (bottom-right) ]
Returns JSON with:
views: {name: {VIEW_X, VIEW_Y, half_w, half_h, look_at, camera, up}}
free_space: {name: {above/below: {x, y, h}, left/right: {x, y, w}}} — the
empty rectangle outside each view edge, bounded by neighbouring views,
the title block, and the margins; budget dimension tiers (n × tier
pitch must fit in h/w) before placing annotations
warnings: list of layout problems (out-of-bounds, title-block overlap)
suggestion: recommended page_w/page_h/scale if the layout does not fit
object_name: name from show() — use "" to measure the current shape
page_w/page_h: sheet size in mm (default A4 landscape 297×210)
scale: drawing scale factor (default 1.0; use 2.0 for 2:1)
views: subset of ["front","plan","side","iso"] to place
title_block_w/h: reserved bottom-right area (default 150×30 mm)
margin: page margin in mm (default 10)
extents: [x, y, z] part sizes in mm — lays out from these numbers instead
of a session object (use when the part isn't loaded, e.g. import failed)
centroid: [x, y, z] look_at origin when using extents (default [0, 0, 0])
Accuracy: front/plan/side positions are exact for orthographic projection.
Iso position is approximate (75% of 3-D diagonal as half-extent) — verify
with render_view() and adjust manually if the iso overlaps a neighbour.
Inputs: scale, views, margin, page_h, +6 more. Returns: result
validateARead-only
Check whether a shape would pass a CAD validity gate before exporting it. Returns a PASS/FAIL verdict plus JSON (passes_gate, n_solids, volume, is_manifold, brep_valid, reasons). The gate mirrors what strict CAD and mesh consumers require: a well-formed (BRepCheck), watertight, manifold solid with non-zero volume. A FAIL means a STEP/STL export would be rejected outright — common causes are a leftover 2D sketch or open shell as the current shape, an un-fused compound, or a degenerate boolean result. Run this immediately before export() on any part you intend to submit or hand off. object_name: named object from show() (default: current shape).
Inputs: object_name. Returns: result
versionARead-only
Return the installed versions of the build123d-mcp server, its key dependencies (build123d, build123d-drafting-helpers), and the companion packages importable inside execute() (bd_warehouse for threads/fasteners/gears/bearings, augura for printability analysis). Use this to confirm which server build is running — e.g. to check whether a feature or fix is present, or whether the client is talking to a stale install.
Inputs: no named parameters. Returns: result
view_axesARead-only
DEPRECATED (#465) — moved to draftwright; off by default in 0.4.0, removed in 0.5.0. Calling it explains the replacement. Return the world→page axis mapping for a project_to_viewport call, computed analytically (no projection performed). Use this BEFORE rendering a projected view to confirm which world axis ends up on which page axis and with what sign — catches bottom-view/side-view axis swaps before they show up in the render.
Returns JSON like {"world_X": ["page_X", -1.0], "world_Y": ["page_Y", 1.0],
"world_Z": ["depth", 0.0]} — for a bottom-view origin (0,0,-100), world-X
flips to negative page-X.
Args:
viewport_origin: camera position, same arg as project_to_viewport.
viewport_up: up vector. Defaults to (0,1,0).
look_at: target point. Defaults to origin.
Inputs: viewport_origin (required), look_at, viewport_up. Returns: result
workflow_hintsARead-only
Return guidance on how to use these tools effectively. Call this at the start of a session or whenever unsure which tool to reach for.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 48 tools
Despite 48 tools, each targets a distinct resource or feature class: session management, geometry analysis, feature recognition, rendering, and export are clearly separated. A few pairs could be confused (measure vs inspect_part, find_bosses vs find_bored_bosses), but descriptions draw clear boundaries, and deprecated tools are explicitly marked as replacements.
Tool names are consistently snake_case with a verb-first pattern for actions (find_*, render_*, save_*, execute, compare, validate). Minor deviations exist where nouns are used as commands (session_state, version, health_check), and one spelling inconsistency ('recognise' vs 'analyze'), but there is no mixing of naming conventions.
48 tools is well beyond the comfortable range, and six of them (lint_drawing, suggest_view_layout, inspect_drawing, render_drawing, save_drawing_annotations, view_axes) are deprecated placeholders that only explain their replacement. While the server's scope is broad (CAD modeling, analysis, feature recognition, drawing, import/export, repair), the sheer number makes the surface heavier than typical MCP servers.
The tool surface covers the full modeling/analysis lifecycle: code execution, geometry measurement, feature recognition, edit transactions, validation, repair guidance, snapshots, import/export, and session management. Minor gaps exist (e.g., no direct parameter-edit tool beyond design_audit, drawing creation moved out), but agents can work around them via execute().
Maintenance
Related MCP Connectors
Headless CAD engine & MCP server for 2D/3D drafting, solids, DXF/SVG export, and automation.
Parametric 3D CAD for AI agents: build print-ready parts, check them, export STL, 3MF or STEP.
MCP server for AI dialogue using various LLM models via AceDataCloud
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseAqualityAmaintenanceEnables AI assistants to render 3D models from OpenSCAD code, generating single views or multiple perspectives with full camera control. Supports animations, custom parameters, and returns base64-encoded PNG images for seamless integration.12516 PyPI173MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI-driven 3D model generation and manipulation using OpenSCAD through natural language commands. Users can create primitives, apply transformations, perform boolean operations, and export models to various formats like STL and OBJ.11 npmMIT
- FlicenseNot gradedqualityDmaintenanceMCP server that exposes CAD geometry reasoning over STEP files to LLMs, allowing natural language queries about parts, assemblies, dimensions, holes, and mass properties.-
- AlicenseNot gradedqualityDmaintenanceMCP server for FreeCAD that enables AI assistants to create and manipulate 3D models via natural language.MIT