使用说明

Onshape MCP服务器

增强型模型上下文协议（MCP）服务器，用于使用Onshape进行程序化CAD建模。

特性

此MCP服务器提供对Onshape的REST API的全面编程访问，实现：

核心能力（45个工具）

文档发现 -搜索并列出项目，查找Part Studios，浏览工作区
参数化草图 -标准平面上的直角、圆、直线和圆弧
功能管理 -拉伸、旋转、加厚、圆角、倒角、布尔和图案特征
装配管理 -创建装配、添加实例、定位零件、创建配合（紧固、滑动、旋转、圆柱形）
装配分析 -干涉检查、位置验证、面部坐标系、身体细节
变量表 -用于参数化设计的Onshape变量表的读写
功能脚本 -计算FeatureScript表达式，获取边界框
出口 -将零件工作室和组件导出到STL、STEP、PARASOLID、GLTF、OBJ
零件工作室管理 -以编程方式创建和管理零件工作室

安装

先决条件

Python 3.10或更高版本
具有API访问权限的Onshape帐户
Onshape API密钥（访问密钥和密钥）

设置

克隆存储库：

git clone https://github.com/hedless/onshape-mcp.git
cd onshape-mcp

创建虚拟环境：

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

安装依赖项：

pip install -e .

设置环境变量：

export ONSHAPE_ACCESS_KEY="your_access_key"
export ONSHAPE_SECRET_KEY="your_secret_key"

或者创建一个 .env 文件：

ONSHAPE_ACCESS_KEY=your_access_key
ONSHAPE_SECRET_KEY=your_secret_key

获取Onshape API键

首选 Onshape开发者门户
使用您的Onshape帐户登录
创建新的API密钥
复制访问密钥和密钥

用法

运行服务器

onshape-mcp

或者直接使用Python：

python -m onshape_mcp.server

使用Claude代码进行配置

添加到您的 ~/.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"
      }
    }
  }
}

重要提示：

使用 绝对路径 到虚拟环境的Python可执行文件
找到你的路： cd onshape-mcp && pwd 获取目录路径
在Windows上：使用 C:/path/to/onshape-mcp/venv/Scripts/python.exe
使用中的实际密钥替换API密钥 Onshape开发者门户
重新启动Claude代码 编辑后 mcp.json

验证它是否有效： 问Claude Code：“你能列出我的Onshape文档吗？”

有关完整的设置说明，请参阅 docs/QUICK_START.md.

可用工具

文档和导航工具

工具	说明
`list_documents`	列出具有过滤和排序功能的文档
`search_documents`	按名称或描述搜索文档
`get_document`	获取详细的文档信息
`get_document_summary`	获取包含工作区和元素的全面摘要
`find_part_studios`	使用可选名称过滤查找零件工作室
`get_elements`	获取工作区中的所有元素（零件工作室、装配、BOM）
`get_parts`	从零件工作室获取所有零件
`create_document`	创建新的Onshape文档
`create_part_studio`	在文档中创建新的零件工作室

装配工具

工具	说明
`create_assembly`	在文档中创建新程序集
`add_assembly_instance`	将零件或子部件实例添加到部件中
`get_assembly`	获取包含实例和引用的程序集结构
`transform_instance`	应用相对变换（英寸/度）。在固定实例上失败。
`set_instance_position`	设置绝对位置（重置旋转）。在固定实例上失败。
`align_instance_to_face`	将一个实例与另一个实例的面对齐
`create_mate_connector`	在具有偏移的面上创建显式配合连接器
`create_fastened_mate`	在两个实例之间创建刚性（紧固）配合
`create_slider_mate`	创建线性运动伙伴。第一个实例相对于第二个实例滑动。
`create_revolute_mate`	创建旋转配合。第一个实例相对于第二个实例旋转。
`create_cylindrical_mate`	创建滑动+旋转配合。第一个实例相对于第二个实例移动。
`delete_feature`	从部件或零件工作室中删除特征（配合、配合连接器等）

装配分析工具

工具	说明
`get_assembly_positions`	获取所有实例的位置、大小和边界（以英寸为单位）
`get_assembly_features`	获取所有功能及其状态（OK/ERROR/SUPRESSED）
`get_body_details`	获取所有零件的面ID、曲面类型、法线和原点
`get_face_coordinate_system`	查询特定面的朝外坐标系
`check_assembly_interference`	使用边界框检测检查重叠/干涉部分

草图工具栏

工具	说明
`create_sketch_rectangle`	带有可选宽度/高度变量引用的矩形
`create_sketch_circle`	带圆心和半径的圆
`create_sketch_line`	从起点到终点的直线
`create_sketch_arc`	带圆心、半径、起始角和终止角的圆弧

支持所有草图工具 plane （正面/顶部/右侧）和 name 参数。尺寸单位为英寸。

特征工具

工具	说明
`create_extrude`	使用深度、可选变量引用和操作类型拉伸草图
`create_thicken`	将草图加厚为具有可选中平面/相反方向的实体
`create_revolve`	围绕具有角度和操作类型的轴（X/Y/Z）旋转草图
`create_fillet`	通过带半径的边ID对边进行圆角处理（支持可变引用）
`create_chamfer`	按带距离的边ID斜切边（支持可变参照）
`create_linear_pattern`	沿轴（X/Y/Z）重复特征，包括距离和计数
`create_circular_pattern`	围绕具有计数和角度分布的轴重复特征
`create_boolean`	通过确定性ID合并、相减或相交实体

变量和特征工具

工具	说明
`get_variables`	从Part Studio变量表中获取所有变量
`set_variable`	设置或更新变量（例如。， `"0.75 in"`)
`get_features`	从Part Studio获取所有功能

功能脚本工具

工具	说明
`eval_featurescript`	计算FeatureScript lambda表达式（只读）
`get_bounding_box`	获取Part Studio中所有零件的严格边界框

导出工具

工具	说明
`export_part_studio`	导出到STL、STEP、PARASOLID、GLTF或OBJ（可选 `partId` 过滤器）
`export_assembly`	导出到STL、STEP或GLTF

建筑

onshape_mcp/
├── api/
│   ├── client.py         # HTTP client with HMAC authentication
│   ├── documents.py      # Document discovery & navigation
│   ├── partstudio.py     # Part Studio management
│   ├── variables.py      # Variable table management
│   ├── assemblies.py     # Assembly lifecycle, mates & features
│   ├── 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 (face-based)
│   └── thicken.py        # Thicken feature builder
├── analysis/
│   ├── interference.py   # Bounding-box interference detection
│   ├── positioning.py    # Instance position queries & alignment
│   └── face_cs.py        # Face coordinate system queries
├── tools/
│   └── __init__.py       # MCP tool definitions
└── server.py             # Main MCP server (45 tools)

例子

示例1：查找并处理项目

# 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

示例2：创建参数化文件柜

# 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"
)

发展

运行测试

该项目具有全面的测试覆盖率 471单元测试.

# 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

有关详细的测试文档，请参阅 docs/TEST.md.

代码格式化

ruff format .
ruff check .

文档

入门指南

docs/QUICK_START.md -Claude Code用户快速入门指南
docs/DEV_SETUP.md -SSE模式的开发环境设置和调试

开发与测试

docs/TEST.md -测试指南和最佳实践
docs/TEST_SUMMARY.md -测试套件概述
文档/专题_ SUMMARY.md -实施细节和统计数据

API与实施

docs/ONSHAPE_API_IMPROVEMENTS.md文件 -API格式修复和BTMSketch-151实现
文档/草图_平面图_参考资料_GUIDE.md -高级：参照几何图元的草图平面
docs/NEXT_STEPS_GEOMETR_REFERENCES.md -几何参考实施路线图
docs/DOCUMENT_DISCOVERY.md -文档发现功能的完整指南
docs/PARTS_ASSEMBLY_TOOLS.md -零件和装配工具文件

项目分析与研究

docs/CARPENTRY_PRINCILES_FOR_CAD.md -如何在CAD中像木匠一样思考
docs/LEARNING_SUMMARY.md -侧板分析和学习总结
docs/DISPLAY_ABINETS_ANALYSIS_SUMMARY.md -展示柜项目分析
docs/AGENT_CREATION_GUIDE.md -CAD代理创建指南
docs/CREATING_CAD_EXPERT_AGENT.md -创建专门的CAD专家代理

知识库和示例

知识库/组件_workflow_guide.md -全面的装配方法（定位、配合、求解器行为）
examples/cabinet_assembly.md -完整示例：带滑动抽屉的橱柜
知识库/ -Onshape特征实例与研究

路线图

当前状态

文档发现和导航（10个工具）
使用矩形、圆形、直线和圆弧创建草图
特征工具：拉伸、旋转、加厚、圆角、倒角、布尔值、图案
全装配管理：紧固、滑动、旋转和圆柱形配合，带基于面的配合连接器
装配分析：干涉检查、位置验证、面坐标系
变量表管理
FeatureScript评估和边界框查询
导出到STL、STEP、PARASOLID、GLTF、OBJ
471综合单元测试
在多部件组件上进行了现场测试（25个实例机柜，66个功能）

在研究

几何图元参照的草图平面 -从现有特征在面上创建草图（请参见文档/草图_平面图_参考资料_GUIDE.md)
查询API调查-如何以编程方式引用几何图形
实体ID映射-了解Onshape的内部ID系统

近期优先事项

[]实施 create_sketch_on_geometry() 木工正确组装橱柜
[]草图约束（重合、平行、相切等）
[]细木工制品的口袋切割和轮廓（护墙板、榫眼）

长期目标

[]绘图创建
[]物料清单（BOM）生成
[]高级约束和关系
[]配置参数支持

木工特殊功能

[]细木工库（护墙板、榫槽、榫卯、燕尾榫）
[]标准硬件模式（货架销、抽屉滑轨）
[]剪切列表生成
[]材料优化（板材布局）
[]组装指令生成

贡献

欢迎投稿！请随时提交拉取请求。

许可证

MIT许可证

致谢

受启发于 OnPy
建立在模型上下文协议
Onshape API文档：https://onshape-public.github.io/docs/

支持

对于问题和疑问：

GitHub问题：https://github.com/hedless/onshape-mcp/issues
Onshape API论坛：https://forum.onshape.com/