onshape-mcp

Claude Code에서 OnShape CAD를 구동하는 MCP 서버: 파라메트릭 모델링(스케치, 돌출, 회전, 필렛, 패턴), FeatureScript 쿼리, STL 내보내기/검증 — OnShape REST API를 통해.

일회성 설정

uv sync --no-editable
uv run --no-editable onshape-mcp setup    # writes ~/.config/onshape-mcp/.env (chmod 600); no-op if it exists
uv run --no-editable onshape-mcp doctor   # auth smoke test against the live API (4 calls)

왜 항상 --no-editable인가? macOS는 여기서 .venv 아래의 파일을 비동기적으로 hidden 플래그로 표시하며, Python ≥3.13.8은 숨겨진 .pth 파일을 건너뜁니다. 따라서 편집(editable) 설치는 동기화 후 몇 분 지나면 조용히 임포트가 중단됩니다. 편집 불가(non-editable) 설치는 .pth를 사용하지 않으므로 영향을 받지 않습니다.

Related MCP server: MCP 3D Printer Server

자격 증명

API 키는 https://dev-portal.onshape.com/keys에서 발급받습니다(액세스 키 + 시크릿 키 쌍). 자격 증명은 오직 ~/.config/onshape-mcp/.env에만 저장되며, 이 파일은 onshape-mcp setup이 권한 600(소유자 읽기/쓰기 전용)으로 생성합니다. 프로젝트 폴더에는 절대 두지 않고, 커밋하지 않으며, 출력하지 않습니다. 변수 이름은 .env.example을 참조하세요. 프로세스 환경(ONSHAPE_ACCESS_KEY / ONSHAPE_SECRET_KEY)은 파일과 둘 다 존재할 때 파일보다 우선합니다.

프로젝트별 등록

서버를 사용하려는 CAD 프로젝트 폴더에서 다음을 실행합니다(/path/to/onshape-mcp는 이 저장소를 클론한 위치로 바꾸세요):

/path/to/onshape-mcp/install.sh

또는 동일하게:

claude mcp add --scope project onshape -- \
  uv run --quiet --no-editable --project /path/to/onshape-mcp onshape-mcp

또는 프로젝트의 .mcp.json에 직접 등록할 수 있습니다:

{
  "mcpServers": {
    "onshape": {
      "command": "uv",
      "args": ["run", "--quiet", "--no-editable", "--project", "/path/to/onshape-mcp", "onshape-mcp"]
    }
  }
}

(--project, --directory가 아닙니다: 서버는 이 저장소의 venv를 확인하지만 호출자의 cwd는 유지합니다. 파일 경로 도구 인자는 어쨌든 절대 경로여야 합니다.) 프로젝트 범위 서버는 첫 대화형 세션에서 "Pending approval"로 표시됩니다. 메시지가 표시되면 승인하세요.

사용법 치트시트 (도구를 구동하는 LLM용)

일반적인 빌드 흐름

create_document (parentId = folder id)   -> documentId, workspaceId, partStudioElementId
import_cad (ABSOLUTE path to .zip/STEP)  -> foreign CAD into an existing workspace [async, +quota]
set_variable (optional, e.g. wall_thk)   -> use "#wall_thk" in later expressions
create_sketch (plane {"default":"TOP"})  -> featureId            [one closed profile per sketch]
extrude (sketchFeatureId, NEW, depth)    -> base solid
create_sketch + extrude REMOVE THROUGH_ALL                       [holes: skip native hole feature]
find_entities (EDGE, radiusBetween)      -> transient ids for fillet/chamfer
fillet_or_chamfer (entityIds)            -> check featureStatus == OK after EVERY feature
pattern / revolve / boolean_parts as needed
export_stl (ABSOLUTE path)               -> compare_stl(candidate, reference)  [mesh: 3D-print, verify]
export_step (ABSOLUTE path)              -> editable STEP B-rep solid           [CAD/prototyping; async, +quota]

철칙

1. 일시(transient) ID는 일부라도 변경(mutation)되면 만료됩니다. ID를 사용하는 도구 호출 직전에 항상 find_entities를 호출하세요. 피처 ID(create\_sketch/extrude/... 로부터)는 안정적이므로, 허용되는 경우(돌출 영역, 패턴 시드, 부울 본체)에는 그쪽을 우선하세요.

2. 단위: 도구 매개변수와 출력은 기본적으로 인치(inch)입니다(units 매개변수로 변경). 치수 문자열은 그대로 전달됩니다: "1.53 in", "25 mm", "#wall_thk * 2". 각도는도(degree)입니다. eval_featurescript 원시 결과는 METERS/radians입니다.

3. featureStatus는 재생성 피드백 루프입니다. OK면 계속하고, ERROR는 피처가 추가되었지만 실패했음을 뜻합니다. update_feature나 delete_feature로 매개변수를 수정한 후 다시 시도하세요. 모든 모델링 호출 후 이를 확인하세요.

4. extrude REMOVE는 기본 범위(defaultScope)의 모든 솔리드에서 영향을 뺍니다. 의도하지 않으면 스튜디오당 파트 하나를 유지하세요.

5. 스케치당 하나의 닫힌 프로파일을 유지하면 돌출 영역 선택이 모호해 봅니다.

6. 파일 경로는 절대 절대(ABSOLUTE)여야 합니다. 서버의 cwd는 프로젝트 폴더가 아닙니다.

7. 절약하세요: 약 2,500회의 API 호출 인상/연간. 폴링하지 말고, 불필요하게 목록을 다시 조회하지 마세요. analyze_stl/compare_stl은 API 호출 비용이 없습니다.

할당량 경고

OnShape EDU/Free 계정에는 연간 API 할당량이 있습니다(~2,500회/사용자/연간). 할당량을 모두 소진하면 402가 반환되며, 백오버로 해결되지 않습니다. 이 서버는 영구 호출 카운터를 ~/.config/onshape-mcp/call_log에 저장하고 누적 합계를 stderr에 기록합니다. OnShape의 내 계정 → 개발자에서 사용량을 모니터링하세요.

개발

uv run --no-editable pytest          # offline tests (no API calls, no credentials needed)
uv run --no-editable onshape-mcp doctor

라이선스

MIT — LICENSE를 참조하세요.