# onshape [Health: Active]

**Category:** 📐 Architecture & Design  
**Repository:** https://github.com/gpambrozio/onshape-mcp  
**GitHub Stars:** 7  
**npm Downloads (last month):** 1103  
**Views:** 10  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/onshape

## Description
Drive Onshape CAD from an assistant: documents, sketches, solid features, assemblies and exports.

## Tools
Capabilities this server exposes over MCP:

- **onshape_login** — Sign in to Onshape by opening a browser. method='api_key' (default) opens a local page that links to the Onshape developer key page and accepts the pasted key pair. method='oauth' runs the OAuth 2.0 authorization-code flow against an app you registered in the Onshape developer portal. The credential is verified against Onshape and stored in the OS keychain. Returns immediately with status 'pending' if the user has not finished yet — poll with onshape_login_status.
- **onshape_login_status** — Wait for, and report on, the login started by onshape_login. Call this repeatedly while the user is in the browser; each call waits up to wait_seconds before returning.
- **onshape_set_api_key** — Store an Onshape access key and secret key directly, without a browser. Use when the user already has a key pair from https://cad.onshape.com/user/developer/apiKeys. The pair is verified against Onshape before it is saved.
- **onshape_auth_status** — Report which Onshape credential is active, where it came from and whether it still works. Secrets are redacted.
- **onshape_logout** — Delete the credential this server stored (keychain entry and config file). Credentials coming from environment variables or from an existing onshape-cli install are not touched.
- **onshape_list_documents** — List documents visible to the signed-in user, most recently modified first.
- **onshape_search_documents** — Find documents by name. Search before creating, so repeated runs do not make duplicates.
- **onshape_get_document** — Read one document's metadata, including its default workspace id.
- **onshape_get_document_summary** — Document metadata plus every workspace and the elements (tabs) inside each — the fastest way to orient in an unfamiliar document and collect the ids other tools need.
- **onshape_create_document** — Create a document. Free Onshape accounts may only create public documents, so pass public=true there. The result carries the new document id and its default workspace id.
- **onshape_update_document** — Change a document's name or description.
- **onshape_delete_document** — Move a document to the trash. This affects the whole document, not a single tab.
- **onshape_get_workspaces** — List a document's workspaces (branches).
- **onshape_get_elements** — List the elements (tabs) in a workspace: Part Studios, assemblies, drawings, Feature Studios.
- **onshape_find_part_studios** — List the Part Studios in a workspace, optionally filtered by a substring of the name.
- **onshape_list_versions** — List the immutable versions of a document, newest first.
- **onshape_create_version** — Snapshot the workspace as an immutable version. Do this before restructuring an existing design: it is the only way back to the previous state, and drawings must reference a version.
- **onshape_delete_element** — Delete one element (tab) from a workspace.
- **onshape_create_part_studio** — Add a Part Studio tab to a workspace. The new element id is at result.response.id.
- **onshape_get_features** — The full feature tree with each feature's id, type, parameters and regeneration state. Large — prefer onshape_measure or onshape_get_parts when you only need the result of the tree.
- **onshape_get_feature_specs** — The parameter ids, enum names and defaults Onshape expects for every feature type in this Part Studio. Read this before hand-writing a payload for onshape_add_feature.
- **onshape_get_sketch_info** — Entities and solved geometry for every sketch in a Part Studio, or for one sketch.
- **onshape_get_body_details** — Bodies, faces and edges with their deterministic ids — the source for explicit edge selection.
- **onshape_get_parts** — The parts a Part Studio produces, with part ids for export and assembly insertion.
- **onshape_mass_properties** — Volume, mass, centroid and inertia for the Part Studio's bodies.
- **onshape_measure** — Body count, overall bounding box in inches and total volume. Use this to check a model matches its intended dimensions before exporting.
- **onshape_clearance** — Minimum distance between two solid bodies in the same Part Studio, each named by part id or by the feature that created it. 0 (clear: false) means they touch or overlap, so this is also the interference check — e.g. a bracket against a dummy servo body. Returns inches and millimetres, plus the closest point on each body.
- **onshape_validate_part_studio** — Count parts and bodies, and fail when the counts do not match the expectations you pass. A cheap regression check after a run of feature edits.
- **onshape_add_feature** — Post a hand-written BTM feature payload to a Part Studio. The escape hatch for feature types this server has no dedicated tool for — read onshape_get_feature_specs first.
- **onshape_update_feature** — Replace an existing feature's payload, e.g. to change a dimension. Post the whole feature JSON.
- **onshape_delete_feature** — Remove one feature from the tree. Features added after it may fail to regenerate.
- **onshape_rollback** — Set the rollback index so features after it are suppressed. Index 0 rolls back to before the first feature.
- **onshape_eval_featurescript** — Run a FeatureScript function against the Part Studio and return its decoded value. The general-purpose way to inspect geometry: 'function(context is Context, queries) { ... }'.
- **onshape_sketch_rectangle** — Add a sketch holding one closed rectangle, ready to extrude. Corners are opposite, in inches.
- **onshape_sketch_circle** — Add a sketch holding one circle.
- **onshape_sketch_line** — Add a sketch holding one line segment. A line alone encloses no region, so it cannot be extruded.
- **onshape_sketch_circle_axis** — Add a sketch with a circle profile and a construction line. onshape_revolve spins the profile around that construction line, which is how you get a torus or a ring.
- **onshape_create_sketch** — Add a sketch from a list of entities: lines, circles, rectangles and arcs. Use this when the single-shape sketch tools cannot express the profile. Close the profile if you intend to extrude it.
- **onshape_sketch_candy_cane_path** — Add a sketch of a straight stem joined to a hooked arc, approximated by segments — a ready-made path for onshape_sweep.
- **onshape_extrude** — Extrude the closed regions of a sketch into a solid. op=NEW makes a body, ADD merges into existing bodies, REMOVE cuts them, INTERSECT keeps the overlap. end_type picks blind, symmetric or through-all; opposite flips the direction.
- **onshape_hole** — Extrude a sketch as a cut (op=REMOVE). Sketch a circle first, then cut it through the body: end_type THROUGH_ALL needs no depth. A sketch on a body's face points out of the body, so pass opposite to cut into it.
- **onshape_thicken** — Give a sketch region a wall thickness instead of a solid depth.
- **onshape_revolve** — Revolve a sketch profile around an axis. With no axis given, the sketch's own construction line is used (see onshape_sketch_circle_axis); otherwise pass axis_ids or an axis query.
- **onshape_sweep** — Sweep the closed regions of one sketch along the edges of another.
- **onshape_fillet** — Round the selected edges. Name the edges with one of: edges (ids), query (FeatureScript), feature (every edge that feature made), all, or circular.
- **onshape_chamfer** — Bevel the selected edges. Selection works exactly as for onshape_fillet.
- **onshape_shell** — Hollow the body out to a wall thickness, removing the selected faces to open it.
- **onshape_draft** — Taper faces away from a neutral plane — the usual requirement for moulded or cast parts.
- **onshape_boolean** — Combine bodies: UNION, SUBTRACTION or INTERSECTION. Subtraction also needs the targets query.
- **onshape_boolean_union** — Merge all modifiable solid bodies into one. The usual cleanup before exporting a single part.
- **onshape_mirror** — Mirror parts, bodies or faces across a plane.
- **onshape_linear_pattern** — Repeat geometry along a direction, at a fixed spacing.
- **onshape_circular_pattern** — Repeat geometry around an axis.
- **onshape_offset_plane** — Add a construction plane offset from a default plane, a face, or another plane.
- **onshape_get_edges** — Every edge of every solid body, with its deterministic id, owning body, type, and for circles and arcs the radius and centre (inches).
- **onshape_find_circular_edges** — Circular edges (full circles and arcs), optionally only those matching a radius, with each one's centre in inches — the usual way to pick hole rims to fillet, or to check where the holes are.
- **onshape_find_edges_by_feature** — Deterministic ids of the edges a given feature created, evaluated by Onshape.
- **onshape_get_variables** — The variable table of a Part Studio: names, expressions and descriptions.
- **onshape_set_variable** — Create or update a variable. Feature tools can then reference it by name (depth_variable, radius_variable, ...) so a dimension lives in one place. Uses the variable table where the account supports it and falls back to an assignVariable feature otherwise; result.route says which was used. On the feature route an existing variable of the same name is rewritten in place, so features built after it pick up the new value (result.action is updated or created).
- **onshape_get_configuration** — The configuration parameters an element exposes, with their ids and allowed values.
- **onshape_encode_configuration** — Turn configuration parameter values into the encoded string other tools accept as `configuration`.
- **onshape_export_stl** — Export the Part Studio as STL, for 3D printing. The file is in millimetres by default, which is what slicers assume; STL carries no unit, so only change `units` if the consumer expects otherwise. Measure the model before exporting it.
- **onshape_export** — Export through Onshape's translation service: STEP, IGES, 3MF, PARASOLID, SOLIDWORKS and others. Slower than STL because the translation is queued server-side.
- **onshape_shaded_view** — Render the element server-side and return the image. Unlike a thumbnail this is generated on demand, so it always shows the current geometry — use it to check a model visually before exporting.
- **onshape_get_thumbnail** — Save Onshape's stored thumbnail. Thumbnails are generated asynchronously and lag edits — prefer onshape_shaded_view to see the current state.
- **onshape_thumbnail_info** — The thumbnail sizes Onshape has rendered for this element, with their hrefs.
- **onshape_create_assembly** — Add an assembly tab to a workspace.
- **onshape_get_assembly** — The assembly's instances, occurrences, mate features and mate connectors.
- **onshape_insert_instance** — Insert a part, a whole Part Studio or another assembly into an assembly. Insert from a version when pulling from a different document.
- **onshape_delete_instance** — Remove one instance from an assembly by its occurrence node id.
- **onshape_transform_instance** — Apply a 4x4 row-major transform (16 numbers, metres) to the given occurrence paths.
- **onshape_get_assembly_features** — The mates, mate connectors, groups and relations defined in an assembly, with their feature ids, payloads and regeneration states.
- **onshape_assembly_mate_connector** — Place an implicit mate connector on an instance by inference (CENTROID, TOP, ...). Its feature id is what onshape_assembly_mate then joins.
- **onshape_assembly_mate** — Join two mate connectors with a mate: FASTENED, REVOLUTE, SLIDER, CYLINDRICAL, PLANAR, and so on. Each connector is an assembly-level mate connector's feature id, or a Part Studio mate connector given as {path: [instance id], connector: feature id} from onshape_get_assembly. The mate's value measures the first connector against the second, so list the moving part first.
- **onshape_assembly_group** — Lock several instances together without individual mates.
- **onshape_assembly_add_feature** — Post a hand-written assembly feature payload — the escape hatch for mate types with no tool here.
- **onshape_update_assembly_feature** — Replace an assembly feature's payload — a mate's type, connectors or limits, a relation's ratio. Post the whole feature JSON, e.g. as onshape_get_assembly_features returns it, inside a BTFeatureDefinitionCall-1406 envelope.
- **onshape_delete_assembly_feature** — Remove a mate, mate connector, group or relation. Relations on a deleted mate stop solving.
- **onshape_assembly_relation** — Couple mates so one drives the other: GEAR (two revolutes, ratio), RACK_AND_PINION (a revolute and a slider, distance per revolution), SCREW (one cylindrical mate, distance per revolution) or LINEAR (two sliders, ratio). Each mate's degree of freedom follows from its type; cylindrical mates contribute whichever the relation needs. Mates missing the parameter relations need (made by hand-written payloads) are completed first and listed in completedMates. Fails if the relation does not regenerate.
- **onshape_get_mate_values** — Where every mate currently sits: each degree of freedom's value, translations in inches and rotations in degrees, keyed by unit (translationZ_in, rotationZ_deg).
- **onshape_set_mate_values** — Drive top-level mates to new positions — turn a revolute, slide a slider — and read them back; relations move the coupled mates too. Values are inches and degrees. Fails when Onshape does not apply a value, which it does silently for mates with limits enabled and for positions the rest of the assembly cannot reach.
- **onshape_get_bom** — The assembly's BOM table.
- **onshape_assembly_mass_properties** — Mass, volume, centroid and inertia for a whole assembly.
- **onshape_create_drawing** — Create a drawing of a part, Part Studio or assembly. The source must be referenced by version — call onshape_create_version first and pass its id as src_version.
- **onshape_get_drawing_views** — The views placed on a drawing sheet.
- **onshape_export_drawing** — Export a drawing as PDF (or DWG/DXF) through the translation service.
- **onshape_create_feature_studio** — Add a Feature Studio tab for custom FeatureScript.
- **onshape_get_feature_studio** — The FeatureScript source of a Feature Studio.
- **onshape_set_feature_studio** — Replace the FeatureScript source of a Feature Studio. The whole file is overwritten.
- **onshape_get_feature_studio_specs** — The feature specifications a Feature Studio defines, for calling its custom features.
- **onshape_get_metadata** — Read the properties of an element, or of one part when part is given.
- **onshape_set_metadata** — Write properties such as part number, description or material. Only editable properties are accepted; read onshape_get_metadata first to find the property ids.
- **onshape_request** — Make an authenticated request to an arbitrary Onshape REST endpoint, for anything the dedicated tools do not cover. Paths start with /api/ and are documented at https://cad.onshape.com/glassworks/explorer. Prefer a dedicated tool when one exists — they normalise the response and validate the result.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "onshape": {
    "command": "npx",
    "args": ["-y","@gpambrozio/onshape-mcp"]
  }
}
```

## Documentation

## What onshape does

onshape exposes Onshape CAD operations as MCP tools. The coverage spans the document hierarchy, including documents, workspaces, elements, Part Studios, Feature Studios, assemblies, and drawings. Agents can create, rename, inspect, version, and delete document content, then work with sketches, solid features, variables, parts, bodies, faces, and edges.

Modeling tools support common sketch and solid operations such as rectangles, circles, lines, extrudes, holes, revolves, sweeps, fillets, chamfers, shells, drafts, booleans, mirrors, and patterns. Dedicated inspection tools return feature trees, sketch geometry, body topology, parts, mass properties, bounding boxes, volume, and validation results. Assemblies can be built from Part Studio instances and configured with mate connectors, mate values, relations, and groups. Drawings can be created, inspected, and exported.

## How it works

The package runs as an MCP server and prefixes its tools with `onshape_`. Responses use an `ok` status with either a result or error details. The `onshape_request` tool provides access to Onshape REST endpoints that are not covered by a dedicated operation.

The first operation that needs Onshape can start browser-based sign-in. API-key login opens a local page for entering a key pair, while OAuth uses an authorization-code flow for an app registered with Onshape. Credentials are checked against Onshape before storage. Login status can be polled while the browser flow is in progress, and existing credentials from `onshape-cli` can be reused.

Feature writes validate regeneration by default instead of relying only on an HTTP success response. Model edits can be checked with measurement or Part Studio validation tools, and a document version can be created before restructuring a design. Image-producing tools return shaded views and thumbnails inline. Large responses are written to disk after exceeding the configured response-size threshold.

## Setup and configuration

Node.js 20 or newer is required. Claude Code can register the server with `npx -y @gpambrozio/onshape-mcp`; Claude Desktop can use the `.mcpb` package from the latest GitHub release. Other clients use an MCP configuration entry that runs the same `npx` command.

No environment variables are required for normal interactive use. Unattended setups can provide `ONSHAPE_ACCESS_KEY` and `ONSHAPE_SECRET_KEY`, and `ONSHAPE_MCP_AUTO_LOGIN=0` prevents automatic browser login. OAuth can use `ONSHAPE_OAUTH_CLIENT_ID` and `ONSHAPE_OAUTH_CLIENT_SECRET`. Other settings select the API host, default document/workspace/element, export directory, credential path, response-size limit, sign-in wait, browser behavior, and request timeout.

## Tools and capabilities

- Manage documents, workspaces, elements, versions, Part Studios, Feature Studios, and metadata.
- Create and inspect sketches, feature trees, bodies, parts, edges, and solid geometry.
- Add, update, delete, and validate features, including hand-written BTM payloads.
- Build assemblies with instances, mate connectors, mates, relations, and BOM data.
- Measure models, calculate mass properties, render views, and export STL or drawings.
- Authenticate with browser login, OAuth, direct API keys, or inherited `onshape-cli` credentials.

## Limitations and notes

Onshape uses inches and degrees throughout these tools; STL exports default to millimetres. Free Onshape accounts can create only public documents, so document creation must use `public=true` for those accounts. Deleting requires an API key with delete permission.

A feature validation error does not undo a completed change. Inspect the model before retrying, especially after a failed request whose application status is uncertain. Deleting or changing a feature can cause later features to fail regeneration. Creating a version before major restructuring is the available way to return to the prior workspace state.

Credentials supplied through environment variables or an existing `onshape-cli` installation are not removed by `onshape_logout`. When no OS keychain is available, the credential file stores the secret with restrictive file and directory permissions.

_Full upstream README: https://allmcps.com/mcp/onshape/readme_