Skip to main content

onshape-jamcp

Just Another MCP server for Onshape CAD. It lets an AI assistant (Claude, Cursor, VS Code, any MCP client) find your documents, model parts, measure them, look at them and export them - in millimeters by default, with a switch for inches, and a switch that decides whether the assistant gets to see screenshots (which costs tokens) or not.

Status: alpha, verified live. 140+ automated tests run against a simulated Onshape, and scripts/smoke_test.py passed 31/31 checks against a real Onshape account (free plan, 2026-11-14): sketch → extrude → fillet → hole → edit → screenshot → STEP/STL export, with orientation and dimensions measured. Chamfer, assemblies with mates and paid-plan behavior are not yet verified live - see what is verified. Re-run the smoke test on your own account (see below).

Highlights

📏 Metric by default Every length you send or receive is in mm. Set ONSHAPE_UNITS=imperial for inches. Angles are always degrees.
👁️ Screenshot review toggle ONSHAPE_SCREENSHOT_REVIEW=true sends renders to the model so it can see its work (≈ 640 tokens per 800×600 image). false only saves them to disk - zero image tokens. Override per call with review.
🔒 Read-only mode ONSHAPE_READ_ONLY=true removes every tool that can modify a document.
🧰 37 focused tools Documents, sketch → extrude / revolve → patterns, mirror, shell, boolean, fillet/chamfer, edit parameters, measure, faces/edges, assemblies, screenshots, STEP/STL export - custom Feature Studio features such as Thread Creator, variables, configurations, part naming, plus escape hatches (raw feature JSON, FeatureScript, any REST endpoint).
🧪 Honest feedback loop Every modeling tool reports the feature's health (OK/WARNING/ERROR) so the model notices failures instead of piling more features on top.

Quick start

1. Create API keys at https://dev-portal.onshape.com/keys (tick Read and Write; Delete only if you want delete_feature). Copy the secret immediately - Onshape shows it once.

2. Add the server to your MCP client. Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "onshape": {
      "command": "uvx",
      "args": ["onshape-jamcp"],
      "env": {
        "ONSHAPE_ACCESS_KEY": "your-access-key",
        "ONSHAPE_SECRET_KEY": "your-secret-key",
        "ONSHAPE_UNITS": "metric",
        "ONSHAPE_SCREENSHOT_REVIEW": "true"
      }
    }
  }
}

Claude Code: claude mcp add onshape -e ONSHAPE_ACCESS_KEY=... -e ONSHAPE_SECRET_KEY=... -- uvx onshape-jamcp

Until the package is published to PyPI, run it from a checkout instead: replace the command with "command": "uv", "args": ["run", "--directory", "/path/to/onshape-jamcp", "onshape-jamcp"]. More clients and details: docs/getting-started.md.

3. Ask for something:

"Create a document called 'Bracket'. In a new Part Studio model a 60 × 40 mm plate, 8 mm thick, with four 5 mm holes 6 mm from the corners and 4 mm fillets on the vertical edges. Show me a screenshot when you're done."

Verify it works against your account

cp .env.example .env        # fill in the two keys
uv run python scripts/smoke_test.py            # on a free plan add --public (see below)

It creates a throw-away document (private; on a free plan Onshape only allows public ones, so pass --public), models a plate, checks the dimensions/orientation/hole volume/fillets/edit/screenshot/ STEP+STL export numerically, then moves the document to Onshape's trash. It prints PASS/FAIL per check. This is the step that confirms the assumptions a simulated Onshape cannot (plane orientation, face normals, extrude direction).

Settings

Set as environment variables (the env block of your MCP client) or CLI flags. The important ones:

Variable Default Meaning
ONSHAPE_ACCESS_KEY / ONSHAPE_SECRET_KEY - Required (or OAuth, next row). API keys.
ONSHAPE_OAUTH_CLIENT_ID / ONSHAPE_OAUTH_CLIENT_SECRET - Alternative to API keys: your own Onshape OAuth app, then onshape-jamcp auth login once. See docs/oauth.md.
ONSHAPE_UNITS metric metric = millimeters, imperial = inches. Flag: --units.
ONSHAPE_SCREENSHOT_REVIEW true Send screenshots to the LLM (true) or only save them (false). Flag: --[no-]screenshot-review.
ONSHAPE_READ_ONLY false Hide all write tools. Flag: --read-only.
ONSHAPE_BASE_URL https://cad.onshape.com Enterprise: https://yourcompany.onshape.com.

Everything else (image size, output folder, timeout, auth mode, API version, log level) is in docs/configuration.md.

Tools

Group Tools
Server get_settings, whoami
Documents list_documents, get_document, create_document, create_element
Inspect list_features, list_parts, get_part_properties, get_body_details, get_assembly, list_custom_features, list_variables, get_configuration, run_featurescript
Model create_sketch, extrude, revolve, circular_pattern, linear_pattern, mirror, shell, boolean, fillet, chamfer, update_feature, delete_feature, add_feature, add_custom_feature
Names, variables, configurations, assemblies rename, set_variable, set_configuration_input, insert_instance, add_mate
Look & export capture_screenshot, export_model
Escape hatch onshape_api_request

Full parameter reference (generated from the code): docs/tools.md.

Documentation

Security notes

  • API keys stay in your MCP client's config / environment. They are never returned by any tool, never logged, and requests are HMAC-signed so the secret is not even sent over the wire. With OAuth the tokens live in a per-user file and are likewise never returned, logged or sent anywhere but Onshape.
  • Onshape's free plan makes every document public. Do not model confidential work there.
  • Write tools act as you on your real documents. Use ONSHAPE_READ_ONLY=true when you only want the assistant to look around, and rely on Onshape's version history as your undo.
  • With screenshot review on, rendered images are sent to your LLM provider like any other message.

Acknowledgements

Prior art that shaped this project: hedless/onshape-mcp (MIT; the Onshape feature JSON conventions were cross-checked against it) and altendky/onshape-mcp. See docs/comparison.md.

License

MIT. Not affiliated with or endorsed by PTC / Onshape.

Metadata

Release files for onshape-jamcp 1.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for onshape-jamcp 1.1.0
File Size Uploaded Provenance Actions
onshape_jamcp-1.1.0.tar.gz 342.7 kB With provenance Details for onshape_jamcp-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for onshape-jamcp 1.1.0
File Interpreter ABI Platform Actions
onshape_jamcp-1.1.0-py3-none-any.whl Python 3 none any Details for onshape_jamcp-1.1.0-py3-none-any.whl

Total release size: 440.6 kB

Release files / onshape_jamcp-1.1.0.tar.gz

Download URL onshape_jamcp-1.1.0.tar.gz
Size 342.7 kB
Tags Source
SHA-256 checksum
How to use checksums
ed748702cfc8fb1ed23ec282d70b827f26979373d59ad6acfe7bb062c351cb74
BLAKE2b-256 checksum
How to use checksums
60600a37a104fc3808c5a5c2c2b80f8c1ab3905319fc77723a69febd2654f463
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / onshape_jamcp-1.1.0-py3-none-any.whl

Download URL onshape_jamcp-1.1.0-py3-none-any.whl
Size 97.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2830d32e23f767284c96bc94d33afe67b00b52d2b504ba2a7904e5f1c3e487fa
BLAKE2b-256 checksum
How to use checksums
f8b330b56ea2077a2947e7649fc90dc5d0ed6a2fa08f6bb26e05a4762b1abcba
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for onshape-jamcp 1.1.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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for onshape_jamcp-1.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page