onshape-mcp

OnShape CAD を Claude Code から操作する 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 インストールは同期の数分後に静かにインポートされなくなります。非 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. 一時 ID は、どのような変更後も無効になります。 ID を消費するツールの直前に、必ず find_entities を呼び出してください。フィーチャー ID（create_sketch/extrude などの戻り値）は安定しているので、受け付けられる場所（押し出し領域、パターンのシード、ブーリアン演算のボディ）ではそちらを優先してください。

2. 単位: ツールのパラメータと出力はデフォルトでインチです（units パラメータで変更可能）。寸法の文字列はそのまま通ります："1.53 in"、"25 mm"、"#wall_thk * 2"。角度は度です。eval_featurescript の生の結果はメートル／ラジアンです。

3. featureStatus は再生成フィードバックループです。OK なら先へ進んでください。ERROR はフィーチャーが追加されたものの失敗したことを意味します。update_feature または delete_feature でパラメータを修正して再試行してください。モデリング呼び出しのたびに確認します。

4. extrude の REMOVE は、スタジオ内の全てのソリッドから除去されます（defaultScope）。意図しない限り、1つのスタジオには1点だけを置いてください。

5. スケッチごとに閉じたプロファイルを 1 つだけにすると、押し出し領域の選択が明確になります。

6. ファイルパスは必ず ABSOLUTE（絶対パス）にしてください（サーバーの cwd はプロジェクトの cwd ではありません）。

7. 節約する: API コール数は年間約 2,500 回です。ポーリングや不要な再一覧は避けてください。analyze_stl/compare_stl はコール数を消費しません。

クォータに関する警告

OnShape の EDU／無料アカウントには年間 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