Onshape MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Onshape MCP Server list my Onshape documents"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Clone the repository:
git clone https://github.com/hedless/onshape-mcp.git
cd onshape-mcpCreate a virtual environment:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activateInstall dependencies:
pip install -e .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_keyGetting Onshape API Keys
Go to Onshape Developer Portal
Sign in with your Onshape account
Create a new API key
Copy the Access Key and Secret Key
Usage
Running the Server
onshape-mcpOr directly with Python:
python -m onshape_mcp.serverConfiguring 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 && pwdto get the directory pathOn Windows: Use
C:/path/to/onshape-mcp/venv/Scripts/python.exeReplace 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 with filtering and sorting |
| Search documents by name or description |
| Get detailed document information |
| Get comprehensive summary with workspaces and elements |
| Find Part Studios with optional name filtering |
| Get all elements (Part Studios, Assemblies, BOMs) in a workspace |
| Get all parts from a Part Studio |
| Create a new Onshape document |
| Create a new Part Studio in a document |
Assembly Tools
Tool | Description |
| Create a new Assembly in a document |
| Add a part or sub-assembly instance to an assembly |
| Get assembly structure with instances and occurrences |
| Apply a relative transform (inches/degrees). Fails on fixed instances. |
| Set absolute position (resets rotation). Fails on fixed instances. |
| Align one instance flush against a face of another |
| Create an explicit mate connector on a face with offsets |
| Create a rigid (fastened) mate between two instances |
| Create a linear motion mate. First instance slides relative to second. |
| Create a rotational mate. First instance rotates relative to second. |
| Create a slide+rotate mate. First instance moves relative to second. |
| Delete a feature (mate, mate connector, etc.) from an assembly or Part Studio |
Assembly Analysis Tools
Tool | Description |
| Get positions, sizes, and bounds of all instances (in inches) |
| Get all features with their state (OK/ERROR/SUPPRESSED) |
| Get face IDs, surface types, normals, and origins for all parts |
| Query the outward-facing coordinate system for a specific face |
| Check for overlapping/interfering parts using bounding box detection |
Sketch Tools
Tool | Description |
| Rectangle with optional variable references for width/height |
| Circle with center point and radius |
| Line from start point to end point |
| 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 |
| Extrude a sketch with depth, optional variable reference, and operation type |
| Thicken a sketch into a solid with optional midplane/opposite direction |
| Revolve a sketch around an axis (X/Y/Z) with angle and operation type |
| Round edges by edge IDs with radius (supports variable references) |
| Bevel edges by edge IDs with distance (supports variable references) |
| Repeat features along an axis (X/Y/Z) with distance and count |
| Repeat features around an axis with count and angle spread |
| Union, subtract, or intersect bodies by deterministic IDs |
Variable & Feature Tools
Tool | Description |
| Get all variables from a Part Studio variable table |
| Set or update a variable (e.g., |
| Get all features from a Part Studio |
FeatureScript Tools
Tool | Description |
| Evaluate a FeatureScript lambda expression (read-only) |
| Get the tight bounding box of all parts in a Part Studio |
Export Tools
Tool | Description |
| Export to STL, STEP, PARASOLID, GLTF, or OBJ (optional |
| 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].idExample 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-htmlFor detailed testing documentation, see docs/TESTING.md.
Code Formatting
ruff format .
ruff check .Documentation
Getting Started
docs/QUICK_START.md - Quick start guide for Claude Code users
docs/DEV_SETUP.md - Development environment setup with SSE mode and debugging
Development & Testing
docs/TESTING.md - Testing guide and best practices
docs/TEST_SUMMARY.md - Test suite overview
docs/FEATURE_SUMMARY.md - Implementation details and statistics
API & Implementation
docs/ONSHAPE_API_IMPROVEMENTS.md - API format fixes and BTMSketch-151 implementation
docs/SKETCH_PLANE_REFERENCE_GUIDE.md - Advanced: Geometry-referenced sketch planes
docs/NEXT_STEPS_GEOMETRY_REFERENCES.md - Roadmap for geometry reference implementation
docs/DOCUMENT_DISCOVERY.md - Complete guide to document discovery features
docs/PARTS_ASSEMBLY_TOOLS.md - Parts and assembly tool documentation
Project Analysis & Research
docs/CARPENTRY_PRINCIPLES_FOR_CAD.md - How to think like a carpenter in CAD
docs/LEARNING_SUMMARY.md - Summary of side panel analysis and learnings
docs/DISPLAY_CABINETS_ANALYSIS_SUMMARY.md - Analysis of display cabinets project
docs/AGENT_CREATION_GUIDE.md - Guide for creating CAD agents
docs/CREATING_CAD_EXPERT_AGENT.md - Creating specialized CAD expert agents
Knowledge Base & Examples
knowledge_base/assembly_workflow_guide.md - Comprehensive assembly methodology (positioning, mates, solver behavior)
examples/cabinet_assembly.md - Complete worked example: cabinet with sliding drawers
knowledge_base/ - Onshape feature examples and research
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 assemblySketch 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
Inspired by OnPy
Built on the Model Context Protocol
Onshape API documentation: https://onshape-public.github.io/docs/
Support
For issues and questions:
GitHub Issues: https://github.com/hedless/onshape-mcp/issues
Onshape API Forum: https://forum.onshape.com/
Available Tools
48 toolsadd_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
Scored across 48 tools
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.
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.
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.
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
Related MCP Connectors
Run 3D CAD operations, pipelines, parametric models and STEP conversions on CAD Cloud with a key
Parametric 3D CAD for AI agents: build print-ready parts, check them, export STL, 3MF or STEP.
CAD in ChatGPT and Claude: editable parts, STEP/STL/drawings, in-chat 3D, automatic checks.
Text-to-CAD: build exact STEP or 3MF/STL on the server, each stated requirement measured.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables programmatic CAD modeling with Onshape through document discovery, parametric sketching, feature management, and gear creation.-
- AlicenseBqualityCmaintenanceEnables OpenAI Codex to drive real Onshape parametric CAD via 69 tools for documents, sketches, features, assemblies, parametric updates, FeatureScript, vision, and export.69MIT
- AlicenseAqualityBmaintenanceEnables 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.93156 npm7MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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