Skip to content
Back to search

onshape-mcp

mcp server for interacting with onshape

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hedless--onshape-mcp/badge.svg)](/listings/hedless--onshape-mcp)

HTML

<a href="/listings/hedless--onshape-mcp"><img src="/api/listings/hedless--onshape-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

2. Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -e .

4. 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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 405 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Onshape MCP Server
  2. Enhanced Model Context Protocol (MCP) server for programmatic CAD modeling with Onshape.
  3. ## Features
  4. This MCP server provides comprehensive programmatic access to Onshape's REST API, enabling:
  5. ### Core Capabilities (45 tools)
  6. - **Document Discovery** - Search and list projects, find Part Studios, navigate workspaces
  7. - **Parametric Sketches** - Rectangles, circles, lines, and arcs on standard planes
  8. - **Feature Management** - Extrude, revolve, thicken, fillet, chamfer, boolean, and pattern features
  9. - **Assembly Management** - Create assemblies, add instances, position parts, create mates (fastened, slider, revolute, cylindrical)
  10. - **Assembly Analysis** - Interference checking, position verification, face coordinate systems, body details
  11. - **Variable Tables** - Read and write Onshape variable tables for parametric designs
  12. - **FeatureScript** - Evaluate FeatureScript expressions, get bounding boxes
  13. - **Export** - Export Part Studios and Assemblies to STL, STEP, PARASOLID, GLTF, OBJ
  14. - **Part Studio Management** - Create and manage Part Studios programmatically
  15. ## Installation
  16. ### Prerequisites
  17. - Python 3.10 or higher
  18. - Onshape account with API access
  19. - Onshape API keys (access key and secret key)
  20. ### Setup
  21. 1. Clone the repository:
  22. ```bash
  23. git clone https://github.com/hedless/onshape-mcp.git
  24. cd onshape-mcp
  25. ```
  26. 2. Create a virtual environment:
  27. ```bash
  28. python -m venv venv
  29. source venv/bin/activate # On Windows: venv\Scripts\activate
  30. ```
  31. 3. Install dependencies:
  32. ```bash
  33. pip install -e .
  34. ```
  35. 4. Set up environment variables:
  36. ```bash
  37. export ONSHAPE_ACCESS_KEY="your_access_key"
  38. export ONSHAPE_SECRET_KEY="your_secret_key"
  39. ```
  40. Or create a `.env` file:
  41. ```
  42. ONSHAPE_ACCESS_KEY=your_access_key
  43. ONSHAPE_SECRET_KEY=your_secret_key
  44. ```
  45. ## Getting Onshape API Keys
  46. 1. Go to [Onshape Developer Portal](https://dev-portal.onshape.com/)
  47. 2. Sign in with your Onshape account
  48. 3. Create a new API key
  49. 4. Copy the Access Key and Secret Key
  50. ## Usage
  51. ### Running the Server
  52. ```bash
  53. onshape-mcp
  54. ```
  55. Or directly with Python:
  56. ```bash
  57. python -m onshape_mcp.server
  58. ```
  59. ### Configuring with Claude Code
  60. Add to your `~/.claude/mcp.json`:
  61. ```json
  62. {
  63. "mcpServers": {
  64. "onshape": {
  65. "command": "/absolute/path/to/onshape-mcp/venv/bin/python",
  66. "args": ["-m", "onshape_mcp.server"],
  67. "env": {
  68. "ONSHAPE_ACCESS_KEY": "your_access_key_here",
  69. "ONSHAPE_SECRET_KEY": "your_secret_key_here"
  70. }
  71. }
  72. }
  73. }
  74. ```
  75. **Important Notes:**
  76. - Use the **absolute path** to your virtual environment's Python executable
  77. - Find your path: `cd onshape-mcp && pwd` to get the directory path
  78. - On Windows: Use `C:/path/to/onshape-mcp/venv/Scripts/python.exe`
  79. - Replace the API keys with your actual keys from [Onshape Developer Portal](https://dev-portal.onshape.com/)
  80. - **Restart Claude Code** after editing `mcp.json`
  81. **Verify it works:**
  82. Ask Claude Code: "Can you list my Onshape documents?"
  83. For complete setup instructions, see [docs/QUICK_START.md](docs/QUICK_START.md).
  84. ## Available Tools
  85. ### Document & Navigation Tools
  86. | Tool | Description |
  87. |------|-------------|
  88. | `list_documents` | List documents with filtering and sorting |
  89. | `search_documents` | Search documents by name or description |
  90. | `get_document` | Get detailed document information |
  91. | `get_document_summary` | Get comprehensive summary with workspaces and elements |
  92. | `find_part_studios` | Find Part Studios with optional name filtering |
  93. | `get_elements` | Get all elements (Part Studios, Assemblies, BOMs) in a workspace |
  94. | `get_parts` | Get all parts from a Part Studio |
  95. | `create_document` | Create a new Onshape document |
  96. | `create_part_studio` | Create a new Part Studio in a document |
  97. ### Assembly Tools
  98. | Tool | Description |
  99. |------|-------------|
  100. | `create_assembly` | Create a new Assembly in a document |
  101. | `add_assembly_instance` | Add a part or sub-assembly instance to an assembly |
  102. | `get_assembly` | Get assembly structure with instances and occurrences |
  103. | `transform_instance` | Apply a relative transform (inches/degrees). Fails on fixed instances. |
  104. | `set_instance_position` | Set absolute position (resets rotation). Fails on fixed instances. |
  105. | `align_instance_to_face` | Align one instance flush against a face of another |
  106. | `create_mate_connector` | Create an explicit mate connector on a face with offsets |
  107. | `create_fastened_mate` | Create a rigid (fastened) mate between two instances |
  108. | `create_slider_mate` | Create a linear motion mate. First instance slides relative to second. |
  109. | `create_revolute_mate` | Create a rotational mate. First instance rotates relative to second. |
  110. | `create_cylindrical_mate` | Create a slide+rotate mate. First instance moves relative to second. |
  111. | `delete_feature` | Delete a feature (mate, mate connector, etc.) from an assembly or Part Studio |
  112. ### Assembly Analysis Tools
  113. | Tool | Description |
  114. |------|-------------|
  115. | `get_assembly_positions` | Get positions, sizes, and bounds of all instances (in inches) |
  116. | `get_assembly_features` | Get all features with their state (OK/ERROR/SUPPRESSED) |
  117. | `get_body_details` | Get face IDs, surface types, normals, and origins for all parts |
  118. | `get_face_coordinate_system` | Query the outward-facing coordinate system for a specific face |
  119. | `check_assembly_interference` | Check for overlapping/interfering parts using bounding box detection |
  120. ### Sketch Tools
  121. | Tool | Description |
  122. |------|-------------|
  123. | `create_sketch_rectangle` | Rectangle with optional variable references for width/height |
  124. | `create_sketch_circle` | Circle with center point and radius |
  125. | `create_sketch_line` | Line from start point to end point |
  126. | `create_sketch_arc` | Arc with center, radius, start angle, and end angle |
  127. All sketch tools support `plane` (Front/Top/Right) and `name` parameters. Dimensions are in inches.
  128. ### Feature Tools
  129. | Tool | Description |
  130. |------|-------------|
  131. | `create_extrude` | Extrude a sketch with depth, optional variable reference, and operation type |
  132. | `create_thicken` | Thicken a sketch into a solid with optional midplane/opposite direction |
  133. | `create_revolve` | Revolve a sketch around an axis (X/Y/Z) with angle and operation type |
  134. | `create_fillet` | Round edges by edge IDs with radius (supports variable references) |
  135. | `create_chamfer` | Bevel edges by edge IDs with distance (supports variable references) |
  136. | `create_linear_pattern` | Repeat features along an axis (X/Y/Z) with distance and count |
  137. | `create_circular_pattern` | Repeat features around an axis with count and angle spread |
  138. | `create_boolean` | Union, subtract, or intersect bodies by deterministic IDs |
  139. ### Variable & Feature Tools
  140. | Tool | Description |
  141. |------|-------------|
  142. | `get_variables` | Get all variables from a Part Studio variable table |
  143. | `set_variable` | Set or update a variable (e.g., `"0.75 in"`) |
  144. | `get_features` | Get all features from a Part Studio |
  145. ### FeatureScript Tools
  146. | Tool | Description |
  147. |------|-------------|
  148. | `eval_featurescript` | Evaluate a FeatureScript lambda expression (read-only) |
  149. | `get_bounding_box` | Get the tight bounding box of all parts in a Part Studio |
  150. ### Export Tools
  151. | Tool | Description |
  152. |------|-------------|
  153. | `export_part_studio` | Export to STL, STEP, PARASOLID, GLTF, or OBJ (optional `partId` filter) |
  154. | `export_assembly` | Export to STL, STEP, or GLTF |
  155. ## Architecture
  156. ```
  157. onshape_mcp/
  158. ├── api/
  159. │ ├── client.py # HTTP client with HMAC authentication
  160. │ ├── documents.py # Document discovery & navigation
  161. │ ├── partstudio.py # Part Studio management
  162. │ ├── variables.py # Variable table management
  163. │ ├── assemblies.py # Assembly lifecycle, mates & features
  164. │ ├── export.py # Part Studio & Assembly export
  165. │ └── featurescript.py # FeatureScript evaluation
  166. ├── builders/
  167. │ ├── sketch.py # Sketch builder (rectangle, circle, line, arc, polygon)
  168. │ ├── extrude.py # Extrude feature builder
  169. │ ├── revolve.py # Revolve feature builder
  170. │ ├── fillet.py # Fillet feature builder
  171. │ ├── chamfer.py # Chamfer feature builder
  172. │ ├── boolean.py # Boolean operations (union, subtract, intersect)
  173. │ ├── pattern.py # Linear & circular pattern builders
  174. │ ├── mate.py # Mate connector & mate builders (face-based)
  175. │ └── thicken.py # Thicken feature builder
  176. ├── analysis/
  177. │ ├── interference.py # Bounding-box interference detection
  178. │ ├── positioning.py # Instance position queries & alignment
  179. │ └── face_cs.py # Face coordinate system queries
  180. ├── tools/
  181. │ └── __init__.py # MCP tool definitions
  182. └── server.py # Main MCP server (45 tools)
  183. ```
  184. ## Examples
  185. ### Example 1: Finding and Working on a Project
  186. ```python
  187. # Search for your project
  188. documents = await search_documents(query="robot arm", limit=5)
  189. # Get the first matching document
  190. doc_id = documents[0].id
  191. # Get comprehensive summary
  192. summary = await get_document_summary(doc_id)
  193. # Find Part Studios in main workspace
  194. workspace_id = summary['workspaces'][0].id
  195. part_studios = await find_part_studios(doc_id, workspace_id, namePattern="base")
  196. # Now work with the Part Studio
  197. elem_id = part_studios[0].id
  198. ```
  199. ### Example 2: Creating a Parametric Cabinet
  200. ```python
  201. # Set variables
  202. await set_variable(doc_id, ws_id, elem_id, "width", "39.5 in")
  203. await set_variable(doc_id, ws_id, elem_id, "depth", "16 in")
  204. await set_variable(doc_id, ws_id, elem_id, "height", "67.125 in")
  205. await set_variable(doc_id, ws_id, elem_id, "wall_thickness", "0.75 in")
  206. # Create side panel sketch
  207. await create_sketch_rectangle(
  208. doc_id, ws_id, elem_id,
  209. name="Side Panel",
  210. plane="Front",
  211. corner1=[0, 0],
  212. corner2=[16, 67.125],
  213. variableWidth="depth",
  214. variableHeight="height"
  215. )
  216. # Extrude to create side
  217. await create_extrude(
  218. doc_id, ws_id, elem_id,
  219. name="Side Extrude",
  220. sketchFeatureId="<sketch_id>",
  221. depth=0.75,
  222. variableDepth="wall_thickness"
  223. )
  224. ```
  225. ## Development
  226. ### Running Tests
  227. The project has comprehensive test coverage with **471 unit tests**.
  228. ```bash
  229. # Run all tests
  230. pytest
  231. # Run with coverage
  232. pytest --cov
  233. # Run specific module tests
  234. pytest tests/api/test_documents.py -v
  235. # Use make commands
  236. make test
  237. make test-cov
  238. make coverage-html
  239. ```
  240. For detailed testing documentation, see [docs/TESTING.md](docs/TESTING.md).
  241. ### Code Formatting
  242. ```bash
  243. ruff format .
  244. ruff check .
  245. ```
  246. ## Documentation
  247. ### Getting Started
  248. - **[docs/QUICK_START.md](docs/QUICK_START.md)** - Quick start guide for Claude Code users
  249. - **[docs/DEV_SETUP.md](docs/DEV_SETUP.md)** - Development environment setup with SSE mode and debugging
  250. ### Development & Testing
  251. - **[docs/TESTING.md](docs/TESTING.md)** - Testing guide and best practices
  252. - **[docs/TEST_SUMMARY.md](docs/TEST_SUMMARY.md)** - Test suite overview
  253. - **[docs/FEATURE_SUMMARY.md](docs/FEATURE_SUMMARY.md)** - Implementation details and statistics
  254. ### API & Implementation
  255. - **[docs/ONSHAPE_API_IMPROVEMENTS.md](docs/ONSHAPE_API_IMPROVEMENTS.md)** - API format fixes and BTMSketch-151 implementation
  256. - **[docs/SKETCH_PLANE_REFERENCE_GUIDE.md](docs/SKETCH_PLANE_REFERENCE_GUIDE.md)** - Advanced: Geometry-referenced sketch planes
  257. - **[docs/NEXT_STEPS_GEOMETRY_REFERENCES.md](docs/NEXT_STEPS_GEOMETRY_REFERENCES.md)** - Roadmap for geometry reference implementation
  258. - **[docs/DOCUMENT_DISCOVERY.md](docs/DOCUMENT_DISCOVERY.md)** - Complete guide to document discovery features
  259. - **[docs/PARTS_ASSEMBLY_TOOLS.md](docs/PARTS_ASSEMBLY_TOOLS.md)** - Parts and assembly tool documentation
  260. ### Project Analysis & Research
  261. - **[docs/CARPENTRY_PRINCIPLES_FOR_CAD.md](docs/CARPENTRY_PRINCIPLES_FOR_CAD.md)** - How to think like a carpenter in CAD
  262. - **[docs/LEARNING_SUMMARY.md](docs/LEARNING_SUMMARY.md)** - Summary of side panel analysis and learnings
  263. - **[docs/DISPLAY_CABINETS_ANALYSIS_SUMMARY.md](docs/DISPLAY_CABINETS_ANALYSIS_SUMMARY.md)** - Analysis of display cabinets project
  264. - **[docs/AGENT_CREATION_GUIDE.md](docs/AGENT_CREATION_GUIDE.md)** - Guide for creating CAD agents
  265. - **[docs/CREATING_CAD_EXPERT_AGENT.md](docs/CREATING_CAD_EXPERT_AGENT.md)** - Creating specialized CAD expert agents
  266. ### Knowledge Base & Examples
  267. - **[knowledge_base/assembly_workflow_guide.md](knowledge_base/assembly_workflow_guide.md)** - Comprehensive assembly methodology (positioning, mates, solver behavior)
  268. - **[examples/cabinet_assembly.md](examples/cabinet_assembly.md)** - Complete worked example: cabinet with sliding drawers
  269. - **[knowledge_base/](knowledge_base/)** - Onshape feature examples and research
  270. ## Roadmap
  271. ### Current Status
  272. - Document discovery and navigation (10 tools)
  273. - Sketch creation with rectangles, circles, lines, and arcs
  274. - Feature tools: extrude, revolve, thicken, fillet, chamfer, boolean, patterns
  275. - Full assembly management: fastened, slider, revolute, and cylindrical mates with face-based mate connectors
  276. - Assembly analysis: interference checking, position verification, face coordinate systems
  277. - Variable table management
  278. - FeatureScript evaluation and bounding box queries
  279. - Export to STL, STEP, PARASOLID, GLTF, OBJ
  280. - 471 comprehensive unit tests
  281. - Live-tested on multi-part assemblies (25-instance cabinet with 66 features)
  282. ### In Research
  283. - **Geometry-referenced sketch planes** - Create sketches on faces from existing features (see [docs/SKETCH_PLANE_REFERENCE_GUIDE.md](docs/SKETCH_PLANE_REFERENCE_GUIDE.md))
  284. - Query API investigation - How to programmatically reference geometry
  285. - Entity ID mapping - Understanding Onshape's internal ID system
  286. ### Near-Term Priorities
  287. - [ ] Implement `create_sketch_on_geometry()` for carpentry-correct cabinet assembly
  288. - [ ] Sketch constraints (coincident, parallel, tangent, etc.)
  289. - [ ] Pocket cuts and profiles for joinery (dados, rabbets)
  290. ### Long-Term Goals
  291. - [ ] Drawing creation
  292. - [ ] Bill of Materials (BOM) generation
  293. - [ ] Advanced constraints and relations
  294. - [ ] Configuration parameter support
  295. ### Woodworking-Specific Features
  296. - [ ] Joinery library (dado, rabbet, mortise & tenon, dovetail)
  297. - [ ] Standard hardware patterns (shelf pins, drawer slides)
  298. - [ ] Cut list generation
  299. - [ ] Material optimization (sheet layout)
  300. - [ ] Assembly instructions generation
  301. ## Contributing
  302. Contributions are welcome! Please feel free to submit a Pull Request.
  303. ## License
  304. MIT License
  305. ## Acknowledgments
  306. - Inspired by [OnPy](https://github.com/kyle-tennison/onpy)
  307. - Built on the [Model Context Protocol](https://modelcontextprotocol.io/)
  308. - Onshape API documentation: https://onshape-public.github.io/docs/
  309. ## Support
  310. For issues and questions:
  311. - GitHub Issues: https://github.com/hedless/onshape-mcp/issues
  312. - Onshape API Forum: https://forum.onshape.com/

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.