cadquery/README.md

CadQuery MCP Server

Ein MCP-Server (Model Context Protocol), der Claude ermöglicht, parametrische 3D-Modelle direkt über CadQuery-Python-Code zu erstellen und als STL-Dateien zu exportieren. Zusätzlich ist CQ-editor als GUI-Vorschau-Tool integriert.

---

Inhaltsverzeichnis

1. Voraussetzungen
2. Installation
3. Claude Code einbinden
4. CQ-editor starten
5. Verwendung in Claude
6. Projektstruktur
7. Fehlerbehebung

---

1. Voraussetzungen

Anforderung	Version	Hinweis
Windows 10/11	64-Bit	Getestet auf Windows 11
Python	≥ 3.10	python.org – „Add to PATH" aktivieren
Claude Code	aktuell	CLI-Tool von Anthropic
Git	optional	Für Versionsverwaltung

Hinweis: Python 3.13 wird vollständig unterstützt (CadQuery 2.7.0 liefert fertige Wheels).

---

2. Installation

2.1 Projektverzeichnis anlegen

mkdir C:\Users\<Benutzername>\Documents\Claude\cadquery
cd    C:\Users\<Benutzername>\Documents\Claude\cadquery

2.2 Python Virtual Environment erstellen

python -m venv .venv

Das erzeugt einen isolierten Python-Interpreter unter .venv\.

2.3 CadQuery, MCP-Server und CQ-editor installieren

.venv\Scripts\pip install cadquery mcp[cli] cq-editor

Installierte Pakete (Auswahl):

Paket	Version	Zweck
cadquery	2.7.0	Parametrisches CAD in Python (OpenCASCADE)
cadquery-ocp	7.8.1	OpenCASCADE Python-Bindings
mcp	1.26.0	Model Context Protocol SDK (FastMCP)
cq-editor	0.6.2	GUI-Editor mit Live-Vorschau (PyQt5)

Downloadgröße: ca. 150 MB (cadquery-ocp ~52 MB, PyQt5-Qt5 ~50 MB, casadi ~51 MB) Bei Verbindungsunterbrechung einfach erneut ausführen – pip setzt den Download fort.

2.4 Installation prüfen

.venv\Scripts\python -c "import cadquery as cq; print('cadquery', cq.__version__)"
# Ausgabe: cadquery 2.7.0

.venv\Scripts\python -c "import cq_editor; print('cq-editor OK')"
# Ausgabe: cq-editor OK

2.5 Output-Verzeichnis anlegen

mkdir models

STL-Dateien und Vorschauen werden in cadquery\models\ gespeichert.

---

3. Claude Code einbinden

Claude Code (CLI) nutzt settings.json — nicht claude_desktop_config.json.

3.1 Konfigurationsdatei

C:\Users\<Benutzername>\.claude\settings.json

3.2 CadQuery-Server eintragen

Den folgenden Block in "mcpServers" einfügen:

{
  "mcpServers": {
    "cadquery": {
      "type": "stdio",
      "command": "C:/Users/<Benutzername>/Documents/Claude/cadquery/.venv/Scripts/python.exe",
      "args": ["C:/Users/<Benutzername>/Documents/Claude/cadquery/server.py"],
      "env": {
        "CADQUERY_OUTPUT_DIR": "C:/Users/<Benutzername>/Documents/Claude/cadquery/models"
      }
    }
  }
}

Wichtig: <Benutzername> durch den tatsächlichen Windows-Benutzernamen ersetzen. Pfade in settings.json werden mit Forward-Slashes (/) geschrieben.

3.3 Claude Code neu starten

Nach Änderungen an settings.json muss Claude Code vollständig neu gestartet werden (nicht nur eine neue Konversation öffnen — die App selbst beenden und neu starten). Die MCP-Tools erscheinen dann automatisch in der Werkzeugliste.

---

4. CQ-editor starten

CQ-editor ist ein Qt-basierter GUI-Editor mit Live-3D-Vorschau.

Starten über die Kommandozeile

# Direkt über die installierte Executable:
.venv\Scripts\cq-editor.exe

# Alternativ über Python:
.venv\Scripts\python -m cq_editor

Workflow mit CQ-editor

1. CQ-editor starten
2. Datei aus models\ öffnen (z.B. box.py)
3. F5 drücken → Live-Vorschau rechts aktualisiert sich
4. Datei → Export → STL zum Speichern

---

5. Verwendung in Claude

5.1 Verfügbare MCP-Tools

Nach dem Neustart von Claude Code stehen drei Tools zur Verfügung:

mcp__cadquery__render_stl

Führt CadQuery-Python-Code aus und exportiert eine STL-Datei nach models\.

Parameter:
  code     : str  – CadQuery-Python-Code
  filename : str  – Ausgabedateiname (Standard: "model.stl")

mcp__cadquery__preview_png

Exportiert eine SVG-Vorschau des Modells nach models\.

Parameter:
  code     : str  – CadQuery-Python-Code
  filename : str  – Ausgabedateiname (Standard: "preview.png")

mcp__cadquery__list_models

Listet alle STL-Dateien in models\ auf.

5.2 Code-Konventionen

Der MCP-Server erkennt das CadQuery-Ergebnis auf zwei Wegen:

Option A — show_object() aufrufen (empfohlen, CQ-editor-kompatibel):

import cadquery as cq

result = cq.Workplane("XY").box(20, 20, 10)
show_object(result)

Option B — Variable result verwenden:

import cadquery as cq

result = cq.Workplane("XY").box(20, 20, 10)
# "result" wird automatisch erkannt

5.3 Beispiele

Offene Box mit parametrischen Maßen (siehe models/box.py):

import cadquery as cq

# Maße
breite      = 30   # mm (X)
tiefe       = 30   # mm (Y)
hoehe       = 20   # mm (Z)
wandstaerke = 2    # mm

result = (
    cq.Workplane("XY")
    .box(breite, tiefe, hoehe)
    .faces(">Z")
    .shell(-wandstaerke)
)

show_object(result)

Zylinder mit Bohrung:

import cadquery as cq

result = (
    cq.Workplane("XY")
    .cylinder(height=30, radius=15)
    .faces(">Z")
    .hole(10)
)
show_object(result)

Quader mit abgerundeten Kanten:

import cadquery as cq

breite = 40
tiefe  = 20
hoehe  = 10
radius = 3

result = (
    cq.Workplane("XY")
    .box(breite, tiefe, hoehe)
    .edges("|Z")
    .fillet(radius)
)
show_object(result)

5.4 Output-Verzeichnis

STL-Dateien und SVG-Vorschauen werden gespeichert in:

cadquery\models\

Der Pfad wird über CADQUERY_OUTPUT_DIR in settings.json gesetzt. Fallback (wenn nicht gesetzt): cadquery\models\ relativ zu server.py.

---

6. Projektstruktur

cadquery/
├── .venv/               # Python Virtual Environment (nicht ins Git)
├── models/              # Generierte STL- und SVG-Dateien + Python-Modelle
│   └── box.py           # Beispiel: offene Box mit parametrischen Maßen
├── server.py            # MCP-Server (FastMCP)
└── README.md            # Diese Datei

server.py – Übersicht

_run_cadquery(code)      Führt CadQuery-Code aus, fängt show_object() ab
render_stl(code, fn)     Tool: exportiert STL über cadquery.exporters
preview_png(code, fn)    Tool: exportiert SVG-Vorschau
list_models()            Tool: listet STL-Dateien in OUTPUT_DIR

---

7. Fehlerbehebung

„Kein CadQuery-Objekt gefunden"

Der Server konnte kein Ergebnis aus dem Code extrahieren.

Lösung: Am Ende des Codes explizit show_object(result) aufrufen oder das Ergebnis in eine Variable namens result speichern.

STL-Datei wird nicht erstellt

• Output-Verzeichnis prüfen: cadquery\models\ muss existieren
• Schreibrechte auf das Verzeichnis prüfen

Claude Code zeigt keine MCP-Tools

1. settings.json auf korrekte Pfade und JSON-Syntax prüfen
2. Claude Code vollständig beenden (nicht nur Konversation schließen)
3. Claude Code neu starten
4. MCP-Server-Log prüfen: %APPDATA%\Claude\logs\mcp-server-cadquery.log

Download bricht ab (cadquery-ocp / PyQt5-Qt5)

Beide Pakete sind ca. 50 MB groß. Bei Abbruch einfach wiederholen:

.venv\Scripts\pip install cadquery mcp[cli] cq-editor --retries 5

CQ-editor startet nicht

# Fehlerausgabe anzeigen:
.venv\Scripts\python -m cq_editor

Häufige Ursache: Fehlende Qt-Laufzeitbibliotheken → Visual C++ Redistributable installieren: aka.ms/vs/17/release/vc_redist.x64.exe

---

Lizenz

MIT License — freie Nutzung, Modifikation und Weitergabe erlaubt.