nova
bae8071e69
- server.py: Output-Verzeichnis default auf models/ relativ zu server.py - README.md: Claude Code statt Desktop, models/-Ordner, korrekte settings.json - models/box.py: Offene Box 30x30x20mm, alle Maße als Variablen Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
330 lines
7.9 KiB
Markdown
330 lines
7.9 KiB
Markdown
# 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](#1-voraussetzungen)
|
||
2. [Installation](#2-installation)
|
||
3. [Claude Code einbinden](#3-claude-code-einbinden)
|
||
4. [CQ-editor starten](#4-cq-editor-starten)
|
||
5. [Verwendung in Claude](#5-verwendung-in-claude)
|
||
6. [Projektstruktur](#6-projektstruktur)
|
||
7. [Fehlerbehebung](#7-fehlerbehebung)
|
||
|
||
---
|
||
|
||
## 1. Voraussetzungen
|
||
|
||
| Anforderung | Version | Hinweis |
|
||
|---|---|---|
|
||
| Windows 10/11 | 64-Bit | Getestet auf Windows 11 |
|
||
| Python | ≥ 3.10 | [python.org](https://www.python.org/downloads/) – „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
|
||
|
||
```powershell
|
||
mkdir C:\Users\<Benutzername>\Documents\Claude\cadquery
|
||
cd C:\Users\<Benutzername>\Documents\Claude\cadquery
|
||
```
|
||
|
||
### 2.2 Python Virtual Environment erstellen
|
||
|
||
```powershell
|
||
python -m venv .venv
|
||
```
|
||
|
||
Das erzeugt einen isolierten Python-Interpreter unter `.venv\`.
|
||
|
||
### 2.3 CadQuery, MCP-Server und CQ-editor installieren
|
||
|
||
```powershell
|
||
.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
|
||
|
||
```powershell
|
||
.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
|
||
|
||
```powershell
|
||
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:
|
||
|
||
```json
|
||
{
|
||
"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
|
||
|
||
```powershell
|
||
# 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):**
|
||
```python
|
||
import cadquery as cq
|
||
|
||
result = cq.Workplane("XY").box(20, 20, 10)
|
||
show_object(result)
|
||
```
|
||
|
||
**Option B — Variable `result` verwenden:**
|
||
```python
|
||
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`):**
|
||
```python
|
||
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:**
|
||
```python
|
||
import cadquery as cq
|
||
|
||
result = (
|
||
cq.Workplane("XY")
|
||
.cylinder(height=30, radius=15)
|
||
.faces(">Z")
|
||
.hole(10)
|
||
)
|
||
show_object(result)
|
||
```
|
||
|
||
**Quader mit abgerundeten Kanten:**
|
||
```python
|
||
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:
|
||
|
||
```powershell
|
||
.venv\Scripts\pip install cadquery mcp[cli] cq-editor --retries 5
|
||
```
|
||
|
||
### CQ-editor startet nicht
|
||
|
||
```powershell
|
||
# 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](https://aka.ms/vs/17/release/vc_redist.x64.exe)
|
||
|
||
---
|
||
|
||
## Lizenz
|
||
|
||
MIT License — freie Nutzung, Modifikation und Weitergabe erlaubt.
|