Build123d MCP

What pzfreo/build123d-mcp does

The pzfreo/build123d-mcp MCP server connects an MCP-compatible AI application to build123d, a Python-based parametric CAD library. It provides a tool-driven workflow for creating 3D parts, checking intermediate results, correcting modeling mistakes, and producing exchange files. The assistant can work in smaller construction steps instead of generating an entire CAD script without feedback.

Typical results include rendered PNG or SVG views, geometry measurements, validation checks, and STEP or STL exports. SVG and DXF export are also supported. The server is intended to be used by an AI application such as Claude, Cursor, VS Code, Continue, Cline, or Codex CLI; it is not itself a chatbot or a full desktop CAD application.

How it works

The normal arrangement is a local stdio connection. The AI application starts the server as a subprocess, then calls its CAD tools through MCP. A practical modeling loop is to create one feature, render or measure it, validate the shape, and export only after the result passes the relevant checks.

For imported STEP geometry, the workflow can identify recognized feature candidates and interface features. A plain through hole can be selected by handle and resized while protecting specified references. The edit is registered only when the hole, other recognized holes, and the outside envelope satisfy the checks described by the project. More complex holes, including counterbores, spotfaces, countersinks, or holes made from multiple constituent faces, must be edited through execute() and checked afterward.

Setup and configuration

The pzfreo/build123d-mcp MCP server can be run without cloning the repository. Install uv, then use Python 3.11, 3.12, 3.13, or 3.14. The documented default command is:

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

Add that command to the MCP configuration used by the chosen client. Claude Code uses a project or user .mcp.json; Claude Desktop and Cursor use their respective MCP configuration files; VS Code, Continue, Cline, and Codex CLI use the configuration mechanism provided by the application or extension. Restarting the client may be necessary after changing its configuration.

For browser-based experimentation, the repository provides a GitHub Codespaces setup with Python, uv, CAD dependencies, headless display packages, and a VS Code MCP configuration. HTTP mode is intended for advanced deployments where the server is hosted separately, but the supplied quick-start path uses stdio.

Tools and capabilities

The available workflow covers:

• Creating and modifying build123d geometry with execute().
• Rendering model views for visual inspection.
• Measuring geometry and checking results with validate().
• Exporting STEP, STL, SVG, and DXF files.
• Finding recognized imported-part candidates with find_candidates().
• Suggesting hole-bearing flat faces with interface_features().
• Editing eligible plain through holes with edit_feature().
• Comparing results with compare(kind="shape").
• Inspecting last_error when an operation needs repair.

Limitations and notes

The server requires an MCP-capable host application and does not provide its own conversational interface. Local use requires uv and a compatible Python version. Imported-part editing is deliberately narrower than general CAD editing: complex hole configurations are refused by the constrained edit path and should instead be handled with execute(), followed by comparison and export checks. Rendering in a development or Codespaces environment also depends on the provided headless display setup.