Auth

AI-assisted access to your Onshape CAD documents.

What This Is

Onshape MCP connects your AI assistant to Onshape. You describe what you want in Onshape terms — create a sketch, extrude a part, export an STL — and the AI handles the API calls. This is a helper for people who already know Onshape, not a replacement for CAD skills.

Status

Early development. This is offered for people to try if they're interested — things may not always work as expected, and feedback is appreciated.

This project does not provide a public hosted MCP server or a public OAuth proxy. Run it locally, self-host it, or connect to a server operated by someone you independently trust.

Getting Started

Local Setup (Claude Desktop, OpenCode, or any MCP client)

This is the recommended path. A local server can read and write files on your machine directly — screenshots, exports, and FeatureScript — instead of passing content through the conversation.

Step 1: Create an Onshape OAuth application

Create your own OAuth application in Onshape with http://localhost:18338/callback as a redirect URL. Keep its client ID and client secret available for onshape-mcp auth login. Direct OAuth with these user-owned credentials is the default. API access and secret keys are also supported as an alternative; see Authentication.

Step 2: Get the server binary

Pick whichever is easier for you:

• npx (requires Node.js): No separate install needed — your MCP client runs npx --yes onshape-mcp and it downloads automatically.
• Pre-built binary: Download from GitHub Releases and save it somewhere convenient.

Step 3: Configure your MCP client

Tell your MCP client how to launch the server.

Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

Using npx:

{
  "mcpServers": {
    "onshape": {
      "command": "npx",
      "args": ["--yes", "onshape-mcp"]
    }
  }
}

Using the downloaded binary:

{
  "mcpServers": {
    "onshape": {
      "command": "/path/to/onshape-mcp"
    }
  }
}

OpenCode

Add to your opencode.json:

Using npx:

{
  "mcp": {
    "onshape": {
      "type": "local",
      "command": ["npx", "--yes", "onshape-mcp"]
    }
  }
}

Using the downloaded binary:

{
  "mcp": {
    "onshape": {
      "type": "local",
      "command": ["/path/to/onshape-mcp"]
    }
  }
}

Other MCP clients

Any MCP client that supports stdio transport can launch this server. The command is either npx --yes onshape-mcp or the path to the downloaded binary.

Step 4: Authenticate and try it

Configure your OAuth client ID and secret, then run npx --yes onshape-mcp auth login when using the npm package, or onshape-mcp auth login when using the downloaded binary. Prefer configuration or ONSHAPE_MCP_AUTH__CLIENT_ID and ONSHAPE_MCP_AUTH__CLIENT_SECRET environment variables. The supported --client-id and --client-secret flags may expose secrets in shell history or process listings. Restart or start your MCP client, then ask your AI assistant to create a new Onshape document with a simple shape.

Experimental Remote Setup

Streamable HTTP remains available for self-hosting, but it is experimental and has not been broadly verified. This project offers no publicly operated endpoint. If an independent operator gives you access, add a placeholder URL such as https://mcp.example.com/mcp to your web MCP client and confirm the operator's trust, access, and retention policies first. ChatGPT connectivity is currently known to fail; see #546.

HTTP transport deliberately disables MCP file reads and writes. File-reference arguments and local output paths therefore cannot access your computer; provide supported request content inline and retrieve remote results through the tool response instead.

Tips

• Share document URLs. Paste an Onshape document URL into the conversation to give the AI context about what you're working with.
• Use Onshape vocabulary. Say "extrude," "fillet," "sketch on the top face," etc. The AI has built-in knowledge about Onshape operations.
• Multiple steps are normal. The AI discovers API endpoints dynamically, so a single request may involve several steps behind the scenes.
• Be specific when things go wrong. If the AI takes a wrong turn, try describing the Onshape operation more precisely.

What You Can Do

• Browse and explore your Onshape documents
• Create new documents and parts
• Build features: sketches, extrudes, revolves, sweeps, fillets, construction planes
• Take screenshots of Part Studios from different angles
• Export parts (STL, STEP, and other formats)
• Work with FeatureScript — write custom features and debug existing ones

The AI has access to the full Onshape REST API, so anything available through the API is potentially reachable. Results will vary — some operations work more reliably than others at this stage.

Supported Platforms

Platform	Architecture
Linux	x86_64, aarch64
macOS	x86_64, aarch64 (Apple Silicon)
Windows	x86_64

Project Documentation

For development, architecture, and contribution details, see docs/src/project/.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.