Jarvis Onshape MCP

Claude Code plugin that lets Claude drive real Onshape CAD: sketches, extrudes, fillets, mates, parametric iteration via Variable Studios, custom FeatureScript features. Every mutating tool returns a structured truth: what changed, what warnings the regenerator raised, and hints for the next move. Multi-view PNG renders come back as image content so Claude can actually see the part.

Includes a vision-decomposition skill that walks Claude through reading an engineering reference image before building. See RESEARCH.md for the benchmark data behind that workflow.

"felt dramatically more like writing code than anything I've tried with an LLM CAD tool."

What you get

• Truth-telling on every mutation. Every tool returns {ok, status, feature_id, feature_name, error_message, changes?, hints?}. Silent regen failures are surfaced, warnings are enriched with actionable fixes.

• Vision. render_part_studio_views and render_assembly_views return shaded PNGs (front/top/right/iso). crop_image zooms in on regions. load_local_image caches a reference image (drawing, photo, sketch) the user shares so you can crop into it the same way. compare_to_reference renders your in-progress part and composites it directly under the reference for side-by-side visual diff in a single image.

• Vision-decomposition skill. /skill vision-decompose — when the user gives you a reference image and asks you to build it, this skill walks you through a structured zoom-and-describe pass before you start building. Produces a feature tree the user can sanity-check. We measured this turns "agent skims image and builds the wrong shape" into "agent reads image carefully, asks the user to confirm, then builds." See the research writeup below.

• Drawing OCR. extract_drawing_dimensions runs Tesseract on an engineering drawing and returns every numeric callout (length / radius / diameter / thread / angle / count) grouped by kind, with pixel positions. Use it on hard-to-read drawing PNGs where small dim text gets clobbered by Claude's vision downsampling.

• Entity discovery with outward normals. list_entities returns deterministic face IDs, surface types, and normals so follow-up features can target geometry without guessing.

• Per-feature geometric diffs. After each feature, you get a changes: block with bbox delta, part count delta, mass delta — you see the effect before rendering.

• Parametric iteration. First-class Variable Studios. set_variable is upsert-by-name, so reparametrizing NEMA 17 → NEMA 23 is a few values away.

• FeatureScript escape hatch. write_featurescript_feature lets Claude write a custom feature directly (helices, swept threads, shells with parameters) when the tool-per-primitive surface isn't enough. Regen errors surface FS notice text.

• Hints rotation. When a feature fails with a known pattern, hints point at the fix (BOOLEAN_SUBTRACT_NO_OP → oppositeDirection, SKETCH_DIMENSION_MISSING_PARAMETER → add missing variable, …).

• Assembly. Fastened, slider, revolute, cylindrical mates; face-coordinate systems; instance alignment; bounding-box interference checks.

Related MCP server: onshape-mcp

Install

/plugin install github:ReshefElisha/jarvis-onshape-mcp

Configure either OAuth (recommended) or an API key pair as described below.

Requirements

• uv on your PATH (brew install uv or the official installer). The plugin launches its MCP server via uv run.

• Claude Code desktop or CLI with plugin support.

• An Onshape account.

OAuth setup

1. In Onshape, open My account > Developer (or your company/classroom/ enterprise Settings > Developer) and create an OAuth application.

2. Register this redirect URL exactly: http://localhost:8765/oauth/callback

3. Copy the application's client ID and client secret into environment variables or an ignored .env file in this repository:

   export ONSHAPE_CLIENT_ID=...
   export ONSHAPE_CLIENT_SECRET=...
   export ONSHAPE_REDIRECT_URI=http://localhost:8765/oauth/callback

   ONSHAPE_REDIRECT_URI is optional and defaults to the URL above. If you change it, register the identical URL in Onshape first. The callback must be an HTTP URL on localhost or 127.0.0.1 and must include a port.

4. Log in from a terminal:

   uv run onshape-mcp oauth-login

The command starts a temporary localhost callback server and opens Onshape in your browser. After authorization, it stores access_token, refresh_token, and expires_at in ~/.config/jarvis-onshape/oauth_tokens.json with file mode 600. Access tokens are refreshed shortly before expiry, and both tokens are replaced when Onshape rotates the refresh token.

When a configured OAuth application has saved tokens, the server uses Bearer authentication. Otherwise it falls back to ONSHAPE_ACCESS_KEY / ONSHAPE_SECRET_KEY, or their existing aliases ONSHAPE_API_KEY / ONSHAPE_API_SECRET. If neither method is available, startup exits with an authentication error.

For API-key fallback, create a key pair under Onshape's Developer settings:

export ONSHAPE_API_KEY=...
export ONSHAPE_API_SECRET=...

Quick start

Once installed, restart Claude Code and try:

"Create a new Onshape document, add a Part Studio, and build me a 60×40×8 mm mounting plate with four ø4 mm holes 6 mm in from the corners."

Claude will render the result, show you the bbox delta, and surface any regen warnings. If it takes a wrong direction on an extrude, the BOOLEAN_SUBTRACT_NO_OP hint will kick in and it'll self-correct.

Protocol guide

Two plugin skills auto-discovered by Claude Code:

• skills/onshape/SKILL.md — CAD build skill. Loaded into every Onshape session. Covers units (bare numbers in mm), coordinate frames (Front is XZ with a Y-normal sign flip), render-first and entity-first workflows, iteration discipline, when to reach for write_featurescript_feature, and the gotchas (REMOVE-on-face auto-flip, Variable Studios as separate elements, deterministic ID remapping).

• skills/vision-decompose/SKILL.md — Vision decomposition. Use this before building when the user shares a reference image. Walks the agent through overview → cache → zoom-into-each-feature → structured spec. Output is a feature tree (type, role, size, position, face) the user can review before committing turns to the build. See "Recommended workflow" below.

You can load either into any Claude session as a system prompt to get the same behavior outside the plugin context.

Recommended workflow

The plugin works best as a copilot, not an autocomplete. Two modes:

Mode A — text-first design. Describe the part in plain text ("a 100×60×30 mm aluminum heat sink with 1mm fins on 3mm pitch and 4 corner Ø3.5 mounting holes") and let Claude build. This works well — the bottleneck is not CAD execution, it's image interpretation.

Mode B — image reference. Drop in a drawing, photo, sketch, or competition prompt and ask Claude to build it.

1. Invoke the vision-decomposition skill: /skill vision-decompose.

2. Claude produces a structured feature tree from the image.

3. Review it — fix mis-reads, fill in things the image didn't make obvious.

4. Tell Claude "build to that spec." It runs the CAD pipeline against the confirmed tree.

Mode B with a careful human review beats letting Claude attempt the whole thing autonomously. See RESEARCH.md for the experimental data behind that recommendation.

Tool surface

Roughly 60 tools across these groups:

Full schemas are discoverable from Claude via ToolSearch — no separate docs to read.

Known limitations

• Section views are blocked at the Onshape platform level. The REST API has no section-view endpoint; only the UI Shift+X works.

• create_fillet with variableCenter currently hits a phantom-reference bug on Onshape's side. Bare radius works.

• opHelix standard-library call is flaky in some contexts; cookbook uses opFitSpline as a workaround.

Development

git clone https://github.com/ReshefElisha/jarvis-onshape-mcp
cd jarvis-onshape-mcp
uv sync
cp .env.example .env       # then fill in OAuth or API-key credentials
uv run onshape-mcp oauth-login
uv run onshape-mcp         # launch the MCP server on stdio
uv run pytest              # unit tests

Attribution

Scaffolding (Onshape REST client + HMAC auth, BTMFeature-134 / BTMParameterQuantity-147 / BTMIndividualQuery-138 payload builders, and the first-pass tool-per-primitive MCP surface) was forked from hedless/onshape-mcp — thanks to hedless for getting that off the ground. Everything built on top of that (truth-telling, vision, entity discovery, parametric Variable Studios, FeatureScript orchestration, per-feature geometric diffs, the hints rotation, iterative agent harness via Claude Agent SDK, and most of the current tool surface) was built here. See NOTICE and git log for the full trail.

License

MIT. See LICENSE.