onshape-mcp

MCP-Server, der OnShape-CAD aus Claude Code heraus steuerbar macht: parametrisches Modellieren (Skizzen, Extrusionen, Umdrehungen/Revolves, Verrundungen, Muster), FeatureScript-Abfragen und STL-Export/-Verifikation — über die OnShape-REST-API.

Einmalige Einrichtung

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)

Warum überall --no-editable? macOS markiert Dateien unter .venv hier asynchron mit dem hidden-Flag, und Python ≥3.13.8 überspringt versteckte .pth-Dateien — Editierbare Installationen werden wenige Minuten nach einer Synchronisierung stillschweigend nicht mehr importiert. Nicht-editierbare Installationen nutzen kein .pth und sind immun.

Related MCP server: MCP 3D Printer Server

Zugangsdaten

API-Schlüssel erhalten Sie von https://dev-portal.onshape.com/keys (ein Paar aus Zugangsschlüssel und Secret-Schlüssel). Zugangsdaten liegen AUSSCHLIESSLICH in ~/.config/onshape-mcp/.env, erzeugt durch onshape-mcp setup mit Berechtigungen 600 (nur Eigentümer kann lesen/schreiben) — niemals in Projektordnern, niemals eingecheckt, niemals ausgegeben. Siehe .env.example für die Variablennamen; die Prozess-Umgebung (ONSHAPE_ACCESS_KEY / ONSHAPE_SECRET_KEY) hat Vorrang vor der Datei, falls beide vorhanden sind.

Registrierung pro Projekt

Führen Sie im CAD-Projektordner, in dem Sie den Server verfügbar machen möchten, Folgendes aus (ersetzen Sie /path/to/onshape-mcp durch den Ort, an den Sie dieses Repository geklont haben):

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

oder gleichwertig:

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

Oder registrieren Sie ihn von Hand in der .mcp.json des Projekts:

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

(--project, nicht --directory: Der Server löst das venv dieses Repos auf, behält aber das Arbeitsverzeichnis des Aufrufers bei. Dateipfad-Tool-Parameter sollen in jedem Fall absolute Pfade sein.) Projektbezogene Server zeigen in der ersten interaktiven Sitzung „Pending approval“ an — bestätigen Sie auf Aufforderung.

Kurzbedienungsübersicht (für das LLM, das die Tools steuert)

Typischer Build-Ablauf

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]

Eiserne Regeln

1. Flüchtige IDs werden nach JEDER Änderung ungültig. Rufen Sie find_entities unmittelbar vor dem Tool-Aufruf auf, der diese IDs konsumiert. Feature-IDs (aus create\_sketch/extrude/...) sind stabil — bevorzugen Sie sie, wo sie akzeptiert werden (Extrude-Bereiche, Muster-Keim, Boolesche Körper).

2. Einheiten: Tool-Parameter und -Ausgaben sind standardmäßig in Zoll (units-Parameter zum Ändern). Dimensions strings werden durchverbunden: "1.53 inches", "25 mm", "#wall_thk * 2". Winkel sind Grad. Rohe Ergebnisse von eval_featurescript sind in METERN/Bogenrad.

3. featureStatus ist die Feedback-Schleife der Neubereitung: OK in Fortfahren; ERROR bedeutet, das Feature wurde hinzugefügt, ist aber fehlgeschlagen — reparieren Sie die Parameter via update_feature oder löschen_feature, und versuchen Sie es erneut. Prüfen Sie ihn nach jedem Modellierungsaufruf.

4. extrude REMOVE subtrahiert von ALLEN Festkörpersen im Studio (defaultScope). Halten Sie in einem Studio nur ein Teil pro Studio, sofern Sie dies nicht beabsichtigen.

5. Ein geschlossenes Profil pro Sketch hält die Extrude-Regionenauswahl eindeutig.

6. Dateipfade müssen ABSOLUTE sein, das cwd des Servers ist nicht das des Projekts.

7. Seien Sie spars den: ~2.500 API-Aufrufe/JAHR. Nicht pollen, nicht unnötig neu listen; analyze_stl/compare_stl kosten keine Aufrufe.

Kontingentwarnung

OnShape EDU/Free-Konten haben ein jährliches API-Kontingent (~2.500 Aufrufe/Benutzer/Jahr); bei Erschöpfung wird ein Fehler 402 (402–??) geliefert, und keine Backoff behebt das. Dieser Server hält einen persistenten Aufrufzähler in ~/.config/onshape-mcp/call_log und fordert den laufenden Gesamtstand auf stderr auf. Überwachen Sie die Nutzung in OnShape unter My Account → Developer.

Entwicklung

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

Lizenz

MIT — siehe LICENSE.