Skip to main content
Glama
Onshape MCP Server

Onshape MCP Server

by hedless

Onshape MCP Server

Enhanced Model Context Protocol (MCP) server for programmatic CAD modeling with Onshape.

Features

This MCP server provides comprehensive programmatic access to Onshape's REST API, enabling:

Core Capabilities (45 tools)

  • Document Discovery - Search and list projects, find Part Studios, navigate workspaces

  • Parametric Sketches - Rectangles, circles, lines, and arcs on standard planes

  • Feature Management - Extrude, revolve, thicken, fillet, chamfer, boolean, and pattern features

  • Assembly Management - Create assemblies, add instances, position parts, create mates (fastened, slider, revolute, cylindrical)

  • Assembly Analysis - Interference checking, position verification, face coordinate systems, body details

  • Variable Tables - Read and write Onshape variable tables for parametric designs

  • FeatureScript - Evaluate FeatureScript expressions, get bounding boxes

  • Export - Export Part Studios and Assemblies to STL, STEP, PARASOLID, GLTF, OBJ

  • Part Studio Management - Create and manage Part Studios programmatically

Related MCP server: onshape-mcp-codex

Installation

Prerequisites

  • Python 3.10 or higher

  • Onshape account with API access

  • Onshape API keys (access key and secret key)

Setup

  1. Clone the repository:

git clone https://github.com/hedless/onshape-mcp.git
cd onshape-mcp
  1. Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  1. Install dependencies:

pip install -e .
  1. Set up environment variables:

export ONSHAPE_ACCESS_KEY="your_access_key"
export ONSHAPE_SECRET_KEY="your_secret_key"

Or create a .env file:

ONSHAPE_ACCESS_KEY=your_access_key
ONSHAPE_SECRET_KEY=your_secret_key

Getting Onshape API Keys

  1. Go to Onshape Developer Portal

  2. Sign in with your Onshape account

  3. Create a new API key

  4. Copy the Access Key and Secret Key

Usage

Running the Server

onshape-mcp

Or directly with Python:

python -m onshape_mcp.server

Configuring with Claude Code

Add to your ~/.claude/mcp.json:

{
  "mcpServers": {
    "onshape": {
      "command": "/absolute/path/to/onshape-mcp/venv/bin/python",
      "args": ["-m", "onshape_mcp.server"],
      "env": {
        "ONSHAPE_ACCESS_KEY": "your_access_key_here",
        "ONSHAPE_SECRET_KEY": "your_secret_key_here"
      }
    }
  }
}

Important Notes:

  • Use the absolute path to your virtual environment's Python executable

  • Find your path: cd onshape-mcp && pwd to get the directory path

  • On Windows: Use C:/path/to/onshape-mcp/venv/Scripts/python.exe

  • Replace the API keys with your actual keys from Onshape Developer Portal

  • Restart Claude Code after editing mcp.json

Verify it works: Ask Claude Code: "Can you list my Onshape documents?"

For complete setup instructions, see docs/QUICK_START.md.

Available Tools

Document & Navigation Tools

Tool

Description

list_documents

List documents with filtering and sorting

search_documents

Search documents by name or description

get_document

Get detailed document information

get_document_summary

Get comprehensive summary with workspaces and elements

find_part_studios

Find Part Studios with optional name filtering

get_elements

Get all elements (Part Studios, Assemblies, BOMs) in a workspace

get_parts

Get all parts from a Part Studio

create_document

Create a new Onshape document

create_part_studio

Create a new Part Studio in a document

Assembly Tools

Tool

Description

create_assembly

Create a new Assembly in a document

add_assembly_instance

Add a part or sub-assembly instance to an assembly

get_assembly

Get assembly structure with instances and occurrences

transform_instance

Apply a relative transform (inches/degrees). Fails on fixed instances.

set_instance_position

Set absolute position (resets rotation). Fails on fixed instances.

align_instance_to_face

Align one instance flush against a face of another

create_mate_connector

Create an explicit mate connector on a face with offsets

create_fastened_mate

Create a rigid (fastened) mate between two instances

create_slider_mate

Create a linear motion mate. First instance slides relative to second.

create_revolute_mate

Create a rotational mate. First instance rotates relative to second.

create_cylindrical_mate

Create a slide+rotate mate. First instance moves relative to second.

delete_feature

Delete a feature (mate, mate connector, etc.) from an assembly or Part Studio

Assembly Analysis Tools

Tool

Description

get_assembly_positions

Get positions, sizes, and bounds of all instances (in inches)

get_assembly_features

Get all features with their state (OK/ERROR/SUPPRESSED)

get_body_details

Get face IDs, surface types, normals, and origins for all parts

get_face_coordinate_system

Query the outward-facing coordinate system for a specific face

check_assembly_interference

Check for overlapping/interfering parts using bounding box detection

Sketch Tools

Tool

Description

create_sketch_rectangle

Rectangle with optional variable references for width/height

create_sketch_circle

Circle with center point and radius

create_sketch_line

Line from start point to end point

create_sketch_arc

Arc with center, radius, start angle, and end angle

All sketch tools support plane (Front/Top/Right) and name parameters. Dimensions are in inches.

Feature Tools

Tool

Description

create_extrude

Extrude a sketch with depth, optional variable reference, and operation type

create_thicken

Thicken a sketch into a solid with optional midplane/opposite direction

create_revolve

Revolve a sketch around an axis (X/Y/Z) with angle and operation type

create_fillet

Round edges by edge IDs with radius (supports variable references)

create_chamfer

Bevel edges by edge IDs with distance (supports variable references)

create_linear_pattern

Repeat features along an axis (X/Y/Z) with distance and count

create_circular_pattern

Repeat features around an axis with count and angle spread

create_boolean

Union, subtract, or intersect bodies by deterministic IDs

Variable & Feature Tools

Tool

Description

get_variables

Get all variables from a Part Studio variable table

set_variable

Set or update a variable (e.g., "0.75 in")

get_features

Get all features from a Part Studio

FeatureScript Tools

Tool

Description

eval_featurescript

Evaluate a FeatureScript lambda expression (read-only)

get_bounding_box

Get the tight bounding box of all parts in a Part Studio

Export Tools

Tool

Description

export_part_studio

Export to STL, STEP, PARASOLID, GLTF, or OBJ (optional partId filter)

export_assembly

Export to STL, STEP, or GLTF

Architecture

onshape_mcp/
├── api/
│   ├── client.py         # HTTP client with HMAC authentication
│   ├── documents.py      # Document discovery & navigation
│   ├── partstudio.py     # Part Studio management
│   ├── variables.py      # Variable table management
│   ├── assemblies.py     # Assembly lifecycle, mates & features
│   ├── export.py         # Part Studio & Assembly export
│   └── featurescript.py  # FeatureScript evaluation
├── builders/
│   ├── sketch.py         # Sketch builder (rectangle, circle, line, arc, polygon)
│   ├── extrude.py        # Extrude feature builder
│   ├── revolve.py        # Revolve feature builder
│   ├── fillet.py         # Fillet feature builder
│   ├── chamfer.py        # Chamfer feature builder
│   ├── boolean.py        # Boolean operations (union, subtract, intersect)
│   ├── pattern.py        # Linear & circular pattern builders
│   ├── mate.py           # Mate connector & mate builders (face-based)
│   └── thicken.py        # Thicken feature builder
├── analysis/
│   ├── interference.py   # Bounding-box interference detection
│   ├── positioning.py    # Instance position queries & alignment
│   └── face_cs.py        # Face coordinate system queries
├── tools/
│   └── __init__.py       # MCP tool definitions
└── server.py             # Main MCP server (45 tools)

Examples

Example 1: Finding and Working on a Project

# Search for your project
documents = await search_documents(query="robot arm", limit=5)

# Get the first matching document
doc_id = documents[0].id

# Get comprehensive summary
summary = await get_document_summary(doc_id)

# Find Part Studios in main workspace
workspace_id = summary['workspaces'][0].id
part_studios = await find_part_studios(doc_id, workspace_id, namePattern="base")

# Now work with the Part Studio
elem_id = part_studios[0].id

Example 2: Creating a Parametric Cabinet

# Set variables
await set_variable(doc_id, ws_id, elem_id, "width", "39.5 in")
await set_variable(doc_id, ws_id, elem_id, "depth", "16 in")
await set_variable(doc_id, ws_id, elem_id, "height", "67.125 in")
await set_variable(doc_id, ws_id, elem_id, "wall_thickness", "0.75 in")

# Create side panel sketch
await create_sketch_rectangle(
    doc_id, ws_id, elem_id,
    name="Side Panel",
    plane="Front",
    corner1=[0, 0],
    corner2=[16, 67.125],
    variableWidth="depth",
    variableHeight="height"
)

# Extrude to create side
await create_extrude(
    doc_id, ws_id, elem_id,
    name="Side Extrude",
    sketchFeatureId="<sketch_id>",
    depth=0.75,
    variableDepth="wall_thickness"
)

Development

Running Tests

The project has comprehensive test coverage with 471 unit tests.

# Run all tests
pytest

# Run with coverage
pytest --cov

# Run specific module tests
pytest tests/api/test_documents.py -v

# Use make commands
make test
make test-cov
make coverage-html

For detailed testing documentation, see docs/TESTING.md.

Code Formatting

ruff format .
ruff check .

Documentation

Getting Started

Development & Testing

API & Implementation

Project Analysis & Research

Knowledge Base & Examples

Roadmap

Current Status

  • Document discovery and navigation (10 tools)

  • Sketch creation with rectangles, circles, lines, and arcs

  • Feature tools: extrude, revolve, thicken, fillet, chamfer, boolean, patterns

  • Full assembly management: fastened, slider, revolute, and cylindrical mates with face-based mate connectors

  • Assembly analysis: interference checking, position verification, face coordinate systems

  • Variable table management

  • FeatureScript evaluation and bounding box queries

  • Export to STL, STEP, PARASOLID, GLTF, OBJ

  • 471 comprehensive unit tests

  • Live-tested on multi-part assemblies (25-instance cabinet with 66 features)

In Research

  • Geometry-referenced sketch planes - Create sketches on faces from existing features (see docs/SKETCH_PLANE_REFERENCE_GUIDE.md)

  • Query API investigation - How to programmatically reference geometry

  • Entity ID mapping - Understanding Onshape's internal ID system

Near-Term Priorities

  • Implement create_sketch_on_geometry() for carpentry-correct cabinet assembly

  • Sketch constraints (coincident, parallel, tangent, etc.)

  • Pocket cuts and profiles for joinery (dados, rabbets)

Long-Term Goals

  • Drawing creation

  • Bill of Materials (BOM) generation

  • Advanced constraints and relations

  • Configuration parameter support

Woodworking-Specific Features

  • Joinery library (dado, rabbet, mortise & tenon, dovetail)

  • Standard hardware patterns (shelf pins, drawer slides)

  • Cut list generation

  • Material optimization (sheet layout)

  • Assembly instructions generation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License

Acknowledgments

Support

For issues and questions:

Available Tools

48 tools
add_assembly_instanceC

Add a part or sub-assembly instance to an assembly

Inputs: elementId (required), documentId (required), workspaceId (required), partStudioElementId (required), +2 more.

align_instance_to_faceA

Position source instance flush against a face of target instance. Faces: front (min Y), back (max Y), left (min X), right (max X), bottom (min Z), top (max Z). Only moves the perpendicular axis; other axes stay unchanged.

Inputs: face (required), elementId (required), documentId (required), workspaceId (required), +2 more.

capture_assembly_screenshotA

Render a shaded-view screenshot of an Assembly's current geometry (for visual verification)

Inputs: elementId (required), documentId (required), workspaceId (required), view, +4 more.

capture_part_studio_screenshotB

Render a shaded-view screenshot of a Part Studio's current geometry (for visual verification)

Inputs: elementId (required), documentId (required), workspaceId (required), view, +4 more.

check_assembly_interferenceA

Check for overlapping/interfering parts in an assembly using bounding box detection. Returns which parts overlap and by how much.

Inputs: elementId (required), documentId (required), workspaceId (required).

create_assemblyB

Create a new Assembly in an existing document

Inputs: name (required), documentId (required), workspaceId (required).

create_booleanB

Perform a boolean operation (union, subtract, intersect) on bodies

Inputs: elementId (required), documentId (required), booleanType (required), toolBodyIds (required), +3 more.

create_chamferC

Create a chamfer (beveled edge) on one or more edges

Inputs: edgeIds (required), distance (required), elementId (required), documentId (required), +3 more.

create_circular_patternB

Create a circular pattern of features around an axis

Inputs: count (required), elementId (required), documentId (required), featureIds (required), +5 more.

create_cylindrical_mateA

Create a cylindrical (slide + rotate) mate between two assembly instances. The first instance slides and rotates relative to the second along the mate connector Z-axis. Requires face IDs from Part Studio body details. Optional offsets shift connectors from face centers.

Inputs: elementId (required), documentId (required), firstFaceId (required), workspaceId (required), +12 more.

create_documentB

Create a new Onshape document

Inputs: name (required), isPublic, description.

create_extrudeC

Create an extrude feature from a sketch

Inputs: depth (required), elementId (required), documentId (required), workspaceId (required), +5 more.

create_fastened_mateA

Create a fastened (rigid) mate between two assembly instances. Requires face IDs from Part Studio body details to place mate connectors on specific faces. Optional offsets shift connectors from face centers (in the face's local XY plane + Z along normal).

Inputs: elementId (required), documentId (required), firstFaceId (required), workspaceId (required), +10 more.

create_filletC

Create a fillet (rounded edge) on one or more edges

Inputs: radius (required), edgeIds (required), elementId (required), documentId (required), +3 more.

create_linear_patternC

Create a linear pattern of features

Inputs: distance (required), elementId (required), documentId (required), featureIds (required), +5 more.

create_mate_connectorA

Create an explicit mate connector on a face of an assembly instance. The connector is placed at the face center with its Z-axis along the face normal. Offsets are in the connector's LOCAL coordinate system (X/Y in-plane, Z along normal). Flipping the Z-axis also reverses the other axes via the right-hand rule, which affects how offset translations map to world space.

Inputs: faceId (required), elementId (required), documentId (required), instanceId (required), +7 more.

create_part_studioB

Create a new Part Studio in an existing document

Inputs: name (required), documentId (required), workspaceId (required).

create_revolute_mateA

Create a revolute (rotation) mate between two assembly instances. The first instance rotates relative to the second around the mate connector Z-axis. Requires face IDs from Part Studio body details. Optional offsets shift connectors from face centers.

Inputs: elementId (required), documentId (required), firstFaceId (required), workspaceId (required), +12 more.

create_revolveB

Create a revolve feature by rotating a sketch around an axis

Inputs: elementId (required), documentId (required), workspaceId (required), sketchFeatureId (required), +4 more.

create_sketch_arcC

Create an arc sketch on a standard plane

Inputs: radius (required), elementId (required), documentId (required), workspaceId (required), +6 more.

create_sketch_circleC

Create a circular sketch on a standard plane

Inputs: radius (required), elementId (required), documentId (required), workspaceId (required), +4 more.

create_sketch_lineB

Create a line sketch on a standard plane

Inputs: endPoint (required), elementId (required), documentId (required), startPoint (required), +3 more.

create_sketch_rectangleC

Create a rectangular sketch in a Part Studio with optional variable references

Inputs: corner1 (required), corner2 (required), elementId (required), documentId (required), +5 more.

create_slider_mateA

Create a slider (linear motion) mate between two assembly instances. The first instance slides relative to the second — positive travel moves the first instance along the face normal direction away from the second. Swap instance order to reverse slide direction. Requires face IDs from Part Studio body details. Optional offsets shift connectors from face centers.

Inputs: elementId (required), documentId (required), firstFaceId (required), workspaceId (required), +12 more.

create_thickenC

Create a thicken feature from a sketch

Inputs: elementId (required), thickness (required), documentId (required), workspaceId (required), +6 more.

create_variable_studioA

Create a new Variable Studio in a document. Variables defined there are shared across all Part Studios in the document and referenced in expressions as #variable_name.

Inputs: name (required), documentId (required), workspaceId (required).

delete_featureC

Delete a feature from a Part Studio or Assembly

Inputs: elementId (required), featureId (required), documentId (required), workspaceId (required), +1 more.

eval_featurescriptB

Evaluate a FeatureScript expression in a Part Studio (read-only, for querying geometry)

Inputs: script (required), elementId (required), documentId (required), workspaceId (required).

export_assemblyC

Export an Assembly to STL, STEP, or other format

Inputs: elementId (required), documentId (required), workspaceId (required), format.

export_part_studioB

Export a Part Studio to STL, STEP, or other format

Inputs: elementId (required), documentId (required), workspaceId (required), format, +1 more.

find_part_studiosB

Find Part Studio elements in a specific workspace, optionally filtered by name

Inputs: documentId (required), workspaceId (required), namePattern.

get_assemblyB

Get assembly structure including instances and occurrences

Inputs: elementId (required), documentId (required), workspaceId (required).

get_assembly_featuresA

Get all features (mates, mate connectors, etc.) from an assembly with their current state (OK, ERROR, SUPPRESSED). Useful for inspecting existing mates and debugging assembly issues.

Inputs: elementId (required), documentId (required), workspaceId (required).

get_assembly_positionsB

Get positions, sizes, and world-space bounds of all instances in an assembly (in inches)

Inputs: elementId (required), documentId (required), workspaceId (required).

get_body_detailsA

Get face-level geometry details for all parts in a Part Studio. Returns face deterministic IDs, surface types (PLANE, CYLINDER, etc.), and for planar faces: normal vectors and origin points. Use face IDs with mate connector tools.

Inputs: elementId (required), documentId (required), workspaceId (required).

get_bounding_boxC

Get the tight bounding box of all parts in a Part Studio

Inputs: elementId (required), documentId (required), workspaceId (required).

get_documentB

Get detailed information about a specific document

Inputs: documentId (required).

get_document_summaryC

Get a comprehensive summary of a document including all workspaces and elements

Inputs: documentId (required).

get_elementsB

Get all elements (Part Studios, Assemblies, etc.) in a workspace

Inputs: documentId (required), workspaceId (required), elementType.

get_face_coordinate_systemA

Query the true outward-facing coordinate system for a face on an assembly instance. Returns the guaranteed outward normal (Z-axis), tangent axes (X/Y), and origin. More reliable than body details normals. Use this to verify face orientations before creating mates.

Inputs: faceId (required), elementId (required), documentId (required), instanceId (required), +1 more.

get_featuresC

Get all features from a Part Studio

Inputs: elementId (required), documentId (required), workspaceId (required).

get_partsB

Get all parts from a Part Studio element

Inputs: elementId (required), documentId (required), workspaceId (required).

get_variablesA

Get all variables from a Variable Studio (variables are shared across the document and referenced as #name)

Inputs: elementId (required), documentId (required), workspaceId (required).

list_documentsB

List documents in your Onshape account with optional filtering and sorting

Inputs: limit, sortBy, sortOrder, filterType.

search_documentsB

Search for documents by name or description

Inputs: query (required), limit.

set_instance_positionA

Set an instance to an ABSOLUTE position in inches (unlike transform_instance which is relative). Resets rotation to identity. Note: fails on fixed/grounded instances (API returns 400).

Inputs: x (required), y (required), z (required), elementId (required), +3 more.

set_variableA

Set or update a variable in a Variable Studio, preserving the other variables. The type (LENGTH/ANGLE/ANY) is inferred from the expression's units

Inputs: name (required), elementId (required), documentId (required), expression (required), +2 more.

transform_instanceA

Apply a RELATIVE transform to an assembly instance (inches and degrees). Note: fails on fixed/grounded instances — use get_assembly_positions to check the 'fixed' flag first.

Inputs: elementId (required), documentId (required), instanceId (required), workspaceId (required), +6 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 48 tools

    Disambiguation4/5

    Most tools map cleanly to a distinct resource and action, and the create/get/delete/set verbs make selection straightforward. However, list_documents and search_documents overlap in purpose, and get_document vs get_document_summary (plus get_elements) could cause an agent to pick the wrong one.

    Naming Consistency5/5

    All tool names use snake_case and nearly all follow a verb_noun pattern: create_*, get_*, list_*, set_*, delete_*, export_*. Even with 48 tools, the naming convention is highly predictable; exceptions like add_assembly_instance or eval_featurescript still fit the verb-first style.

    Tool Count2/5

    48 tools is well beyond the 25+ threshold and feels over-fragmented for an MCP surface. Several sets, such as create_sketch_line/circle/arc/rectangle and the four mate creators, could be consolidated into parameterized operations without losing clarity.

    Completeness3/5

    The server covers document discovery, part studio feature creation, assembly construction, mates, export, and screenshots—so the core CAD workflow is present. However, there are notable lifecycle gaps: no update or delete for documents, no removal of assembly instances, and no way to edit existing features besides deleting them.

    Maintenance

    ActivityStale
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Enables OpenAI Codex to drive real Onshape parametric CAD via 69 tools for documents, sketches, features, assemblies, parametric updates, FeatureScript, vision, and export.
      69
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to drive Onshape CAD with 87 tools for documents, part studios, sketching, solid features, assemblies, drawings, measurement, and export, including zero-configuration browser sign-in.
      93
      156 npm
      7
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables Claude to create and modify real, editable Onshape CAD models through the Onshape REST API, covering parametric sketches, solid features, configurations, assemblies with mates and motion tests, interference checks, FeatureScript custom features, versions/branches, and import/export.
      MIT