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 (35 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, fillet, chamfer, boolean, and pattern features
- 🏗️ Assembly Management - Create assemblies, add instances, position parts, create mates
- 📊 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
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-mcp
- Create a virtual environment:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
- Install 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_key
Getting 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-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 && pwdto 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 (filterType, sortBy, sortOrder, limit) |
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 |
get_assembly |
Get assembly structure with instances and occurrences |
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 |
transform_instance |
Position/rotate an instance using translation (inches) and rotation (degrees) |
create_fastened_mate |
Create a rigid mate between two instances |
create_revolute_mate |
Create a rotational mate between two instances |
📐 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 (NEW/ADD/REMOVE/INTERSECT) |
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 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 authentication
│ ├── documents.py # Document discovery & navigation
│ ├── partstudio.py # Part Studio management
│ ├── variables.py # Variable table management
│ ├── assemblies.py # Assembly lifecycle & mates
│ ├── 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
│ └── thicken.py # Thicken feature builder
├── tools/
│ └── __init__.py # MCP tool definitions
└── server.py # Main MCP server (35 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 353 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
black .
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
- 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, fillet, chamfer, boolean, patterns
- ✅ Assembly management with mates and transforms
- ✅ Variable table management
- ✅ FeatureScript evaluation and bounding box queries
- ✅ Export to STL, STEP, PARASOLID, GLTF, OBJ
- ✅ 353 comprehensive unit tests (86%+ coverage)
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.)
- Slider and cylindrical mate types
- 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/
Metadata
Release files for iflow-mcp_hedless-onshape-mcp 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_hedless_onshape_mcp-0.2.0.tar.gz | 175.8 kB | Without provenance | Details for iflow_mcp_hedless_onshape_mcp-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_hedless_onshape_mcp-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_hedless_onshape_mcp-0.2.0-py3-none-any.whl |
Total release size: 226.6 kB
Release files / iflow_mcp_hedless_onshape_mcp-0.2.0.tar.gz
| Download URL | iflow_mcp_hedless_onshape_mcp-0.2.0.tar.gz |
|---|---|
| Size | 175.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
18bc330f55974503ecadf43255ec6798eccb06df3d31e954283aa32667dbacbd
|
|
BLAKE2b-256 checksum How to use checksums |
43c6a1d5d55f14f1e3381ad37bc89fcd85d7fa99dc633e4719fac17c01d7f93e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_hedless_onshape_mcp-0.2.0-py3-none-any.whl
| Download URL | iflow_mcp_hedless_onshape_mcp-0.2.0-py3-none-any.whl |
|---|---|
| Size | 50.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1a2f6f12bcbb0e2a556b3055f8f41eca7a046224835703af53d71cf1b870b317
|
|
BLAKE2b-256 checksum How to use checksums |
8caaeae628ecf6ea2284f902447de831bbbd62754629c8140628dbd399350e07
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_hedless-onshape-mcp 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.