onshape

Onshape MCP 服务

通过 AI 助手操作 Onshape CAD。提供 88 个工具，可用于文档、零件工作室、草图绘制、实体特征、装配体、工程图、测量和导出——安装后无需其他设置：首次调用需要 Onshape 的工具时，会打开浏览器并提示你连接。

"Make a 60 × 40 × 10 mm bracket with 4 mm mounting holes and 2 mm fillets, then show me a render"

助手会绘制草图、拉伸、倒圆边缘、测量结果、将渲染图显示在对话中，并导出可供打印的 STL。

安装

Claude Code

claude mcp add onshape -- npx -y @gpambrozio/onshape-mcp

Claude Desktop — 从最新版本下载 onshape-mcp-<version>.mcpb，然后双击即可。无需安装其他内容。

Cursor、VS Code、Windsurf、Zed 和其他 MCP 客户端 — 将服务添加到客户端的 MCP 配置中：

{
  "mcpServers": {
    "onshape": {
      "command": "npx",
      "args": ["-y", "@gpambrozio/onshape-mcp"]
    }
  }
}

配置文件因客户端而异：~/.cursor/mcp.json（Cursor）、.vscode/mcp.json （VS Code）、~/.codeium/windsurf/mcp_config.json（Windsurf）、~/.config/zed/settings.json 中的 context_servers（Zed）。

需要 Node 20 或更高版本。首次运行时，npx 会获取此软件包。

登录

无需配置。首次调用需要 Onshape 的工具时，会启动登录流程，并要求客户端显示链接；支持 MCP URL 询问的客户端会将其显示为提示词，其他客户端则会在回复中提供 URL。打开的页面会直接跳转到你的 Onshape 实例对应的密钥页面，并接受粘贴的密钥对；创建密钥时，请勾选 Read、Write 和 Delete，以确保这里的所有工具都能正常使用。密钥会通过 Onshape 验证，然后存储在你的 OS 密钥链中。

你的凭据绝不会经过助手、模型或本项目的作者——整个交互都在你的浏览器与此进程中绑定到 127.0.0.1 的服务之间进行，这正是 MCP 提供 URL 询问功能的原因。

如果你更喜欢其他方式，也可以：

• onshape_login — 主动启动相同的流程。
• onshape_set_api_key — 粘贴已有的密钥对。
• OAuth 2.0 — 使用 method: "oauth" 调用 onshape_login，适用于你在 Onshape 开发者门户注册的应用；重定向 URL 为 http://localhost:8471/oauth/callback。令牌会自动刷新。
• 环境变量 — 设置 ONSHAPE_ACCESS_KEY 和 ONSHAPE_SECRET_KEY，用于无人值守安装；设置 ONSHAPE_MCP_AUTO_LOGIN=0，可禁止服务打开浏览器。

现有的 onshape-cli 凭据会从 ~/.onshape/credentials.json 自动读取。

onshape_auth_status 会显示当前使用的凭据（已脱敏）；onshape_logout 会将其清除。

工具

区域	工具
登录	login, login_status, set_api_key, auth_status, logout
文档	list_documents, search_documents, get_document, get_document_summary, create_document, update_document, delete_document, get_workspaces, get_elements, find_part_studios, list_versions, create_version, delete_element
零件工作室	create_part_studio, get_features, get_feature_specs, get_sketch_info, get_body_details, get_parts, mass_properties, measure, clearance, validate_part_studio, add_feature, update_feature, delete_feature, rollback, eval_featurescript
草图绘制	sketch_rectangle, sketch_circle, sketch_line, sketch_circle_axis, create_sketch, sketch_candy_cane_path
实体	extrude, hole, thicken, revolve, sweep, fillet, chamfer, shell, draft, boolean, boolean_union, mirror, linear_pattern, circular_pattern, offset_plane
几何	get_edges, find_circular_edges, find_edges_by_feature
变量	get_variables, set_variable, get_configuration, encode_configuration
导出	export_stl, export, shaded_view, get_thumbnail, thumbnail_info
装配体	create_assembly, get_assembly, insert_instance, delete_instance, transform_instance, get_assembly_features, assembly_mate_connector, assembly_mate, assembly_group, assembly_add_feature, get_bom, assembly_mass_properties
工程图	create_drawing, get_drawing_views, export_drawing
特征工作室	create_feature_studio, get_feature_studio, set_feature_studio, get_feature_studio_specs
元数据	get_metadata, set_metadata
备用接口	request

所有名称均以 onshape_ 为前缀，每个工具都会返回 {"ok": true, "result": …} 或 {"ok": false, "error": …, "detail": …}。

值得了解：

• 单位始终为英寸和度数，但 STL 导出除外；默认使用毫米，因为切片软件都采用这种单位。
• 特征工具默认会验证。 对于无法重新生成的特征，Onshape 仍会返回 200，因此每个工具都会重新读取特征状态，并明确报错。传入 validate: false 可跳过验证。
• 渲染结果会以图像形式返回。 shaded_view 和 get_thumbnail 会内联返回 PNG，同时也会写入文件，因此模型可以看到零件。
• 大型读取结果会写入磁盘。 超过 ONSHAPE_MCP_MAX_RESPONSE_BYTES（默认 200 kB）的内容会写入文件并生成摘要，避免特征树占满上下文窗口。
• onshape_request 可访问专用工具未涵盖的任何 REST 端点。

配置

所有设置均为可选。

变量	作用
ONSHAPE_ACCESS_KEY, ONSHAPE_SECRET_KEY	使用此密钥对，而非登录
ONSHAPE_BASE_URL	Onshape API 主机（默认 https://cad.onshape.com）
ONSHAPE_OAUTH_CLIENT_ID, ONSHAPE_OAUTH_CLIENT_SECRET	使用 OAuth 应用登录，而非 API 密钥
ONSHAPE_MCP_AUTO_LOGIN	0 可阻止工具调用启动浏览器登录
ONSHAPE_MCP_NO_BROWSER	1 表示绝不启动浏览器；改为报告 URL
ONSHAPE_MCP_SIGNIN_WAIT_MS	调用等待登录的时长（默认 120000）
ONSHAPE_DOC, ONSHAPE_WS, ONSHAPE_ELEM	默认目标；设置后可省略这些参数
ONSHAPE_MCP_OUTPUT_DIR	相对导出路径的保存位置（默认：工作目录）
ONSHAPE_MCP_MAX_RESPONSE_BYTES	超过此响应大小后写入文件（默认 200000）
ONSHAPE_MCP_CONFIG	凭据文件路径（默认 ~/.onshape-mcp/credentials.json）
ONSHAPE_TIMEOUT_MS	每个请求的超时时间（默认 120000）

如果系统提供钥匙串，机密信息会保存到 OS 钥匙串（服务 onshape-mcp），配置文件中只保存非机密元数据。如果没有钥匙串，文件会保存机密信息，并以 0600 权限写入权限为 0700 的目录。

Onshape 账户限制

这些限制来自 Onshape，而非此服务：

• 免费账户只能创建公开文档 — 将 public: true 传递给 onshape_create_document。
• 删除需要具有删除权限的密钥。 如果没有该权限，Onshape 会返回 403 Invalid API key state；请前往 cad.onshape.com/user/developer/apiKeys 重新创建密钥，并勾选 Delete。
• 部分账户上的变量表端点会返回 404。 onshape_set_variable 和 onshape_get_variables 会回退到 assignVariable 特征，该方式适用于 所有账户；result.route / result.source 会说明采用了哪条路径。设置 已有 Variable 特征的名称时，会直接改写该特征。

开发

npm install
npm run check     # type-check
npm test          # unit tests, no network and no browser
npm run build
npm run bundle    # build the Claude Desktop .mcpb

node scripts/smoke.mjs           # live read-only check against your account
node scripts/smoke.mjs --write   # also builds a throwaway part

目录结构：src/auth（凭据存储、密钥链、登录流程、OAuth、请求信息）， src/api（REST 封装）、src/builders（Onshape BTM 特征负载）、 src/tools（MCP 接口）、src/server.ts（注册和身份验证门控）。

欢迎贡献 — 请参阅 CONTRIBUTING.md。安全问题报告： SECURITY.md。

许可证

MIT。部分内容源自 onshape-cli — 请参阅 NOTICE。

与 Onshape 或 PTC 无关联，未获其认可或支持。“Onshape”是 PTC Inc. 的商标。