partsmith MCP server
Commit Nov 4, 2026Lets an AI client author, render, validate, and export 3D-printable parts using build123d Python code.
Also known as JLay2026/partsmith
- Stars
- 4
- Tools
- 21
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 4, 2026
- License
- MIT
What is partsmith MCP?
partsmith lets an AI client author, render, validate, and export 3D-printable parts using build123d Python code. It exposes 21 tools, such as partsmith_health, partsmith_create_model, partsmith_modify_model.
Summary generated from the project's README
About partsmith MCP server
Designing and validating 3D-printable parts through an AI agent is what partsmith enables. By wrapping the build123d Python library, this server allows LLM clients like Claude to author parametric CAD models using code. It provides a headless environment that can be deployed on a Linux host or via Docker, accessible through a REST API or a Streamable-HTTP MCP endpoint.
Users can visualize their designs immediately with 3D shaded views, 2D orthographic projections, or cross-sections returned as PNG images. The system includes specialized tools for verifying printability, such as checking for manifold geometry and ensuring a part fits within a specific build volume. It also supports interference testing to check the clearance between two different models.
To manage iterative design, the server includes a versioning system that tracks changes to both the source code and the geometry, such as volume and surface area. Once a design is finalized, it can be exported to STL, STEP, or 3MF formats, including the ability to arrange multiple parts onto a single print plate.
What you can do with it
- 1Generate parametric 3D modelsAsk the AI to create a custom bracket with specific screw hole patterns using Python code.
- 2Verify printer compatibilityCheck if a newly designed part will actually fit on your specific 3D printer's build plate.
- 3Test mechanical assemblyDetermine if a peg will fit into a socket or if two parts will collide before starting a print.
- 4Compare design iterationsAnalyze the geometric differences in volume and surface area between two versions of a part.
Written from the project's README. Every use case is checked against a quote from it.
partsmith MCP tools 21
Detected from the READMEpartsmith_healthpartsmith_create_modelpartsmith_modify_modelpartsmith_list_modelspartsmith_measure_modelpartsmith_render_3dpartsmith_render_2dpartsmith_render_multiviewpartsmith_render_sectionpartsmith_render_drawingpartsmith_exportpartsmith_export_plate
Show all 21 toolsShow fewer tools
partsmith_analyze_printabilitypartsmith_check_fitpartsmith_save_designpartsmith_load_designpartsmith_get_designpartsmith_list_designspartsmith_delete_designpartsmith_list_versionspartsmith_diff_designs
Configuration
PARTSMITH_URL
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablejlay2026/partsmith is public and reachablegithub.com/jlay2026/partsmith ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-04github.com/jlay2026/partsmith ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model21 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubpartsmith
A parametric-CAD server built for AI agents. partsmith wraps build123d (OpenCascade) behind a small REST API and a Model Context Protocol (MCP) endpoint, so an LLM client like Claude can design real, printable 3D parts by writing build123d Python — then render, measure, validate, version, and export them, all over a single HTTP surface.
It's headless, single-file-simple, and designed to live on a small
Linux host behind an authenticating reverse proxy. The container does
no authentication itself — the perimeter is the security boundary (see
SECURITY.md).
What it does
- Author parts in build123d Python (
result = Box(30, 20, 10)), with a library of helpers auto-injected for common 3D-printing patterns (screw holes, slots, fillets, mounting patterns). - See inside designs: 3D shaded views, 2D orthographic projections with dimensions, multiview composites, and cross-sections through any plane — all returned as inline PNGs without leaving the chat.
- Validate printability: watertight / manifold / minimum-dimension checks, plus a build-volume fit check against your printer's bed (v0.4.0), before you ever open a slicer.
- Check mating parts (v0.4.0): interference and clearance between two models — does the hole land on the boss, does the peg fit the socket — before printing either one.
- Persist + version designs to disk: every save is a new version,
with a
diffthat reports source changes + geometry deltas (volume, surface area, bounding box) between any two versions. - Export to STL / STEP / 3MF, including several parts on one print plate as a single 3MF.
Everything works identically over REST and MCP — both share the same in-process engine, so a model authored via one protocol is visible to the other.
Install
Option A — ZimaOS Custom Install (recommended for homelab)
partsmith ships a docker-compose.yml with x-casaos metadata in
JLay2026/zimaboard-services.
Paste it into the ZimaOS dashboard's Custom Install, fill the form,
click Install. See
docs/partsmith-setup.md
there for the full walkthrough (including the one-time bind-mount chown
step).
Option B — docker run from the published image
Every vX.Y.Z tag publishes ghcr.io/jlay2026/partsmith:X.Y.Z (linux/amd64),
signed keyless with cosign (GitHub OIDC) and carrying a signed SPDX SBOM
attestation. There is no latest tag since 0.4.3: pin a version, or a
version and digest. Verify a pull with
cosign verify --certificate-oidc-issuer https://token.actions.githubusercontent.com \
--certificate-identity-regexp '^https://github\.com/JLay2026/partsmith/\.github/workflows/release\.yml@refs/tags/v' \
ghcr.io/jlay2026/partsmith:0.4.3
# Pre-create bind-mount dirs as uid 1000 (the container's user).
# Skipping this makes every export/render return a permission-denied 500.
sudo mkdir -p /srv/partsmith/workspace /srv/partsmith/renders
sudo chown -R 1000:1000 /srv/partsmith/workspace /srv/partsmith/renders
docker run -d --name partsmith \
-p 127.0.0.1:8123:8123 \
-v /srv/partsmith/workspace:/workspace \
-v /srv/partsmith/renders:/renders \
ghcr.io/jlay2026/partsmith:0.4.3
curl http://127.0.0.1:8123/health
# {"status":"ok","version":"0.4.3"}
Available tags: https://github.com/JLay2026/partsmith/pkgs/container/partsmith.
Option C — local dev (build from source)
git clone https://github.com/JLay2026/partsmith
cd partsmith
pip install -e .
python -m uvicorn src.server:app --host 0.0.0.0 --port 8123
curl http://localhost:8123/health
Or build the container locally: docker compose up -d --build
(pre-create + chown workspace/ and renders/ as uid 1000 first, as
above).
The image installs against constraints.txt, a
locked, tested dependency set (v0.4.0+), so builds are reproducible.
For local dev, pip install -c constraints.txt -e . gets the same set.
Connect an MCP client
partsmith exposes a Streamable-HTTP MCP server at /mcp/. URL-based
MCP clients (Cowork's managed MCP UI, Claude Code, etc.) register it
directly — no shim process.
| Field | Value |
|---|---|
| URL | <your-base-url>/mcp/ (trailing slash required) |
| Transport | streamable-http |
| Auth | Whatever your reverse proxy enforces (send headers via the client's Headers field) |
On connect, the client sees the full partsmith_* tool surface (21
tools as of v0.4.0).
Naming tip for agents: use one stable name per part and re-save it
as you iterate (bracket → bracket → bracket), not
bracket_v1 → bracket_v2. The design store versions automatically,
and only same-name versions can be diffed. Since v0.4.0, saving a
version-suffixed name returns a warning pointing at the base name.
build123d helpers
The execution namespace for every create_model / save_design call
has from build123d import * and import numpy as np pre-loaded, plus
seven helpers for patterns that recur in real designs:
| Helper | What it makes |
|---|---|
through_hole(diameter, depth) |
Plain cylindrical hole |
screw_hole(diameter, depth, countersink=True, ...) |
Machine-screw hole, M-series defaults |
hex_hole(across_flats, depth) |
Nut pocket (M3=5.5, M4=7, M5=8, M6=10 mm) |
slot(length, width, depth) |
Stadium-shaped slot for adjustable mounts |
chamfer_edges(part, radius, edges='all'|'top'|'bottom'|'side') |
Chamfer with edge selection |
fillet_top_edges(part, radius) |
Round all top-face edges |
screw_pattern(positions, hole_func) |
Apply a hole at each (x, y) |
# Wall bracket: 4 countersunk holes, top edges filleted
body = Box(100, 50, 10)
holes = screw_pattern(
[(10, 10), (90, 10), (10, 40), (90, 40)],
lambda: screw_hole(3.2, 10),
).moved(Location((0, 0, 10)))
result = fillet_top_edges(body - holes, radius=1.5)
Design store + versioning
Models live in memory and are wiped on container restart. Designs
live on disk under {workspace}/designs/{name}/ and survive restarts,
with one vN.py + vN.json pair per version:
designs/bracket/
v1.py v1.json
v2.py v2.json
v3.py v3.json
save_design(name, code)appends the next version (or passversion=Nto overwrite a slot).load_design(name)loads the latest (or a specific version) and registers it as a model.diff_designs(name, v1, v2)returns a unified source diff plus volume / surface-area / bounding-box deltas — "is v3 actually better than v2 in the ways I care about?" answered at a glance.
REST tool surface
| Endpoint | Method | Purpose | Since |
|---|---|---|---|
/health |
GET | {"status":"ok","version":"X"} |
v0.1 |
/model/create |
POST | Execute build123d code, store as named model, return geometry + base64 preview | v0.1 |
/model/modify |
POST | Re-execute for an existing name | v0.1 |
/model/list |
GET | List loaded models | v0.1 |
/model/{name}/measure |
GET | Bounding box, volume, area, topology counts | v0.1 |
/render/3d |
POST | 3D shaded view (Lambertian), base64 PNG | v0.1 |
/render/2d |
POST | 2D orthographic view + optional dimensions | v0.1 |
/render/multiview |
POST | Composite: front + right + top + iso | v0.1 |
/render/section |
POST | 2D cross-section on XY/XZ/YZ at an offset | v0.2.6 |
/render/drawing |
POST | Dimensioned engineering drawing (overall W/H + title block) | v0.3.4 |
/render/all |
POST | Render every standard view to disk | v0.1 |
/export |
POST | Export STL / STEP / 3MF as binary | v0.1 |
/export/plate |
POST | Several models on one plate as one 3MF (names, layout=arrange|as_modeled, gap_mm, bed_mm); placements in X-Partsmith-Plate header |
v0.4.0 |
/analyze/printability |
POST | Watertight / manifold / min-dimension + bed-fit check (bed_mm override) |
v0.1 (bed-fit v0.4.0) |
/analyze/fit |
POST | Interference + clearance between two models (name_a, name_b, min_clearance_mm, offset_b) |
v0.4.0 |
/workspace/{filename} |
GET | Stream a previously-exported file (MCP large-file fallback) | v0.2 |
/design/save |
POST | Save a design version (also executes as a model) | v0.2.4 |
/design/list |
GET | List saved designs (latest of each) | v0.2.4 |
/design/{name} |
GET | Load source + metadata (?version=N) |
v0.2.4 |
/design/{name} |
DELETE | Delete a version, or all (?version=N) |
v0.2.4 |
/design/{name}/load |
POST | Load + execute a design as a model (?version=N) |
v0.2.4 |
/design/{name}/versions |
GET | List version numbers | v0.2.7 |
/design/{name}/diff |
GET | Diff two versions (?v1=&v2=) |
v0.2.7 |
MCP tools
All prefixed partsmith_ to avoid collisions in multi-server setups.
| Tool | Purpose | Since |
|---|---|---|
partsmith_health |
Status + version + transport | v0.2 |
partsmith_create_model |
Execute build123d code, register as model, return geometry + preview | v0.2 |
partsmith_modify_model |
Re-execute against an existing name | v0.2 |
partsmith_list_models |
List loaded models | v0.2 |
partsmith_measure_model |
Bounding box, volume, area, counts | v0.2 |
partsmith_render_3d |
3D shaded view | v0.2 |
partsmith_render_2d |
2D orthographic projection | v0.2 |
partsmith_render_multiview |
2×2 composite | v0.2 |
partsmith_render_section |
Cross-section through a plane | v0.2.6 |
partsmith_render_drawing |
Dimensioned engineering drawing + title block | v0.3.4 |
partsmith_export |
Export STL / STEP / 3MF | v0.2 |
partsmith_export_plate |
Several models on one print plate as one 3MF (side-by-side by default) | v0.4.0 |
partsmith_analyze_printability |
Watertight / manifold / min-dimension + bed-fit check | v0.2 (bed-fit v0.4.0) |
partsmith_check_fit |
Interference + clearance between two models | v0.4.0 |
partsmith_save_design |
Save a design version | v0.2.4 |
partsmith_load_design |
Load + execute a saved design | v0.2.4 |
partsmith_get_design |
Read a saved design's source (no execution) | v0.4.0 |
partsmith_list_designs |
List saved designs | v0.2.4 |
partsmith_delete_design |
Delete a design / version | v0.2.4 |
partsmith_list_versions |
List a design's versions | v0.2.7 |
partsmith_diff_designs |
Diff two versions (source + geometry deltas) | v0.2.7 |
File handoff: inline vs URL
Tools that return files (partsmith_render_*, partsmith_export)
inline the bytes as base64 when ≤ PARTSMITH_INLINE_MAX_BYTES
(default 8 MiB). Larger payloads persist to the workspace and
return a url_path the client fetches via GET /workspace/<filename>
with the same auth headers.
| Response shape | When | Client action |
|---|---|---|
{"inline": true, "data_b64": "..."} |
≤ 8 MiB | base64-decode and use |
{"inline": false, "url_path": "/workspace/foo.stl"} |
> 8 MiB | GET base_url + url_path |
Configuration
| Env var | Default | Purpose |
|---|---|---|
PARTSMITH_WORKSPACE |
/workspace |
Where exports + saved designs land |
PARTSMITH_RENDERS |
/renders |
Where rendered PNGs are cached |
PARTSMITH_HOST |
0.0.0.0 |
Server bind address |
PARTSMITH_PORT |
8123 |
Server bind port |
PARTSMITH_MAX_BODY_BYTES |
1048576 (1 MiB) |
Reject REST requests larger than this. /mcp is exempt. |
PARTSMITH_INLINE_MAX_BYTES |
8388608 (8 MiB) |
MCP file payloads above this return a url_path instead of inlining. |
PARTSMITH_BED_MM |
256,256,256 (Bambu X1C) |
Build volume x,y,z in mm for the printability bed-fit check. Per-call bed_mm overrides it. |
Operational notes
- Models are in-memory; designs are on disk. Container restart
wipes the model registry (LRU-capped at 32) but never the design
store. Use
save_designto persist anything you want to keep. - Cross-protocol state is shared — REST and MCP wrap the same
CADEngine. - Single uvicorn worker by default — concurrent renders serialize.
Fine for single-user; add
--workers Ninentrypoint.shfor parallelism (~+500 MB resident per worker). - Bind-mount perms — the container runs as uid 1000;
workspace/andrenders/must be writable by that uid. v0.1.3+ surfaces perm failures as a 500 naming the exact path + expected uid.
Testing
Two GitHub Actions workflows run on every PR + push to main:
-
ci.yml—rufflint + a lightweightpytestjob (tests/test_versioning.py+tests/test_bed_fit.py, pure stdlib, ~15 s). -
integration.yml— builds the container, starts it, and runstests/integration/against/health,/mcp/, and the REST surface (REST/MCP parity checks since v0.4.0). A single MCP handshake test guards against the v0.2.x deploy-bug classes (lifespan crash, double-prefixed URL, DNS-rebinding 421, stateful long-poll hang). Run locally with:docker run -d --rm -p 127.0.0.1:8123:8123 --name p-test \ ghcr.io/jlay2026/partsmith:0.4.3 PARTSMITH_URL=http://127.0.0.1:8123 pytest tests/integration/ -v docker stop p-test
Deploy
The production deploy lives in
JLay2026/zimaboard-services
(partsmith/docker-compose.yml + docs/partsmith-setup.md), fronted
by Caddy with LAN/Tailscale-only matchers. partsmith is reached at
https://cad.<your-internal-domain>/ and its MCP endpoint at
/mcp/. The container itself is loopback-bound; all external access
goes through the proxy perimeter.
Project docs
ROADMAP.md— themes, status, release sequenceCHANGELOG.md— every release with the "why"SECURITY.md— threat model ("perimeter is the boundary")NOTICE.md— credit to prior build123d-MCP work
Why this exists
There were a few existing build123d-MCP wrappers when this started. We
shipped a new one because (a) the most prominent existing project had
a SyntaxError sitting in its main file for four months with nobody
noticing, and (b) the wrapped surface is small enough (~1,400 LOC) that
owning it outright is cheaper than maintaining a patched fork. The
project follows a "small over capable" principle — every feature has
to justify its line count, and new patterns get added when a real
design has demanded them, not on speculation.
See NOTICE.md for credit to prior work.
License
MIT — see LICENSE.
partsmith MCP questions
What tools does partsmith MCP provide?
It exposes 21 tools, including partsmith_health, partsmith_create_model, partsmith_modify_model, partsmith_list_models, partsmith_measure_model.
How can an AI agent design parts with partsmith?
The agent can write build123d Python code to author parts, utilizing auto-injected helpers for common patterns like screw holes and fillets.
Can I check if a part will fit on my 3D printer's bed?
Yes, the server includes a build-volume fit check against your printer's bed dimensions.
Does partsmith provide version control for designs?
Yes, every save creates a new version, and you can diff versions to see source changes and geometry deltas like volume and surface area.