# onshape-mcp

MCP server that drives OnShape CAD from Claude Code: parametric modeling
(sketches, extrudes, revolves, fillets, patterns), FeatureScript queries, and
STL export/verification — via the OnShape REST API.

## One-time setup

```bash
uv sync --no-editable
uv run --no-editable onshape-mcp setup    # writes ~/.config/onshape-mcp/.env (chmod 600); no-op if it exists
uv run --no-editable onshape-mcp doctor   # auth smoke test against the live API (4 calls)
```

> **Why `--no-editable` everywhere?** macOS asynchronously marks files under
> `.venv` with the `hidden` flag here, and Python ≥3.13.8 skips hidden `.pth`
> files — editable installs silently stop importing minutes after a sync.
> Non-editable installs don't use `.pth` and are immune.

## Credentials

API keys come from https://dev-portal.onshape.com/keys (an access key +
secret key pair). Credentials live ONLY in `~/.config/onshape-mcp/.env`,
created by `onshape-mcp setup` with permissions `600` (owner read/write
only) — never in project folders, never committed, never printed. See
[.env.example](.env.example) for the variable names; the process
environment (`ONSHAPE_ACCESS_KEY` / `ONSHAPE_SECRET_KEY`) takes precedence
over the file if both exist.

## Per-project registration

From the CAD project folder where you want the server available (replace
`/path/to/onshape-mcp` with wherever you cloned this repo):

```bash
/path/to/onshape-mcp/install.sh
```

or equivalently:

```bash
claude mcp add --scope project onshape -- \
  uv run --quiet --no-editable --project /path/to/onshape-mcp onshape-mcp
```

Or register it by hand in the project's `.mcp.json`:

```json
{
  "mcpServers": {
    "onshape": {
      "command": "uv",
      "args": ["run", "--quiet", "--no-editable", "--project", "/path/to/onshape-mcp", "onshape-mcp"]
    }
  }
}
```

(`--project`, not `--directory`: the server resolves this repo's venv but keeps
the caller's cwd. File-path tool params should be absolute paths regardless.)
Project-scoped servers show "Pending approval" on the first interactive
session — approve when prompted.

## Usage cheatsheet (for the LLM driving the tools)

**Typical build flow**

```
create_document (parentId = folder id)   -> documentId, workspaceId, partStudioElementId
import_cad (ABSOLUTE path to .zip/STEP)  -> foreign CAD into an existing workspace [async, +quota]
set_variable (optional, e.g. wall_thk)   -> use "#wall_thk" in later expressions
create_sketch (plane {"default":"TOP"})  -> featureId            [one closed profile per sketch]
extrude (sketchFeatureId, NEW, depth)    -> base solid
create_sketch + extrude REMOVE THROUGH_ALL                       [holes: skip native hole feature]
find_entities (EDGE, radiusBetween)      -> transient ids for fillet/chamfer
fillet_or_chamfer (entityIds)            -> check featureStatus == OK after EVERY feature
pattern / revolve / boolean_parts as needed
export_stl (ABSOLUTE path)               -> compare_stl(candidate, reference)  [mesh: 3D-print, verify]
export_step (ABSOLUTE path)              -> editable STEP B-rep solid           [CAD/prototyping; async, +quota]
```

**Iron rules**

1. **Transient IDs go stale after ANY mutation.** Always call `find_entities`
   immediately before the tool call that consumes the ids. Feature IDs
   (from create_sketch/extrude/...) are stable — prefer them where accepted
   (extrude regions, pattern seeds, boolean bodies).
2. **Units**: tool params and outputs are inches by default (`units` param to
   change). Dimension strings pass through: `"1.53 in"`, `"25 mm"`,
   `"#wall_thk * 2"`. Angles are degrees. `eval_featurescript` raw results
   are METERS/radians.
3. **featureStatus** is the regen feedback loop: `OK` proceed; `ERROR` means
   the feature was added but failed — fix parameters via `update_feature` or
   `delete_feature` and retry. Check it after every modeling call.
4. **extrude REMOVE subtracts from ALL solids** in the studio (defaultScope).
   Keep one part per studio unless you intend that.
5. One closed profile per sketch keeps extrude region selection unambiguous.
6. File paths must be ABSOLUTE (the server's cwd is not the project's).
7. Be frugal: ~2,500 API calls/YEAR. Don't poll, don't re-list needlessly;
   analyze_stl/compare_stl cost zero calls.

## Quota warning

OnShape EDU/Free accounts have an annual API quota (~2,500 calls/user/year);
exhaustion returns 402 and no backoff fixes it. This server keeps a persistent
call counter at `~/.config/onshape-mcp/call_log` and logs a running total to
stderr. Monitor usage in OnShape under My Account → Developer.

## Development

```bash
uv run --no-editable pytest          # offline tests (no API calls, no credentials needed)
uv run --no-editable onshape-mcp doctor
```

## License

MIT — see [LICENSE](LICENSE).