Initial commit: CadQuery MCP Server
- server.py: FastMCP-Server mit render_stl, preview_png, list_models - README.md: Ausführliche Installationsanleitung (DE) - .gitignore: Schließt .venv, STL/PNG-Ausgaben und Cache aus Stack: cadquery 2.7.0, mcp 1.26.0, cq-editor 0.6.2, Python 3.13 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
nova
@@ -0,0 +1,363 @@
|
||||
# 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 Desktop einbinden](#3-claude-desktop-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 Desktop | aktuell | [claude.ai/download](https://claude.ai/download) |
|
||||
| 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 Test-STL erzeugen
|
||||
|
||||
```powershell
|
||||
.venv\Scripts\python -c "
|
||||
import cadquery as cq
|
||||
from cadquery import exporters
|
||||
from pathlib import Path
|
||||
|
||||
output = Path.home() / '3d-models'
|
||||
output.mkdir(exist_ok=True)
|
||||
result = cq.Workplane('XY').box(20, 20, 10)
|
||||
exporters.export(result, str(output / 'test_box.stl'))
|
||||
print('OK:', output / 'test_box.stl')
|
||||
"
|
||||
```
|
||||
|
||||
Die STL-Datei wird in `C:\Users\<Benutzername>\3d-models\` gespeichert.
|
||||
|
||||
---
|
||||
|
||||
## 3. Claude Desktop einbinden
|
||||
|
||||
### 3.1 Konfigurationsdatei öffnen
|
||||
|
||||
```
|
||||
%APPDATA%\Claude\claude_desktop_config.json
|
||||
```
|
||||
|
||||
Unter Windows typischerweise:
|
||||
```
|
||||
C:\Users\<Benutzername>\AppData\Roaming\Claude\claude_desktop_config.json
|
||||
```
|
||||
|
||||
### 3.2 CadQuery-Server eintragen
|
||||
|
||||
Den folgenden Block in `"mcpServers"` einfügen:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"cadquery": {
|
||||
"command": "C:\\Users\\<Benutzername>\\Documents\\Claude\\cadquery\\.venv\\Scripts\\python.exe",
|
||||
"args": ["C:\\Users\\<Benutzername>\\Documents\\Claude\\cadquery\\server.py"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Wichtig:** `<Benutzername>` durch den tatsächlichen Windows-Benutzernamen ersetzen.
|
||||
> Backslashes müssen in JSON doppelt escapt werden (`\\`).
|
||||
|
||||
Vollständiges Beispiel mit OpenSCAD-Server:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"openscad": {
|
||||
"command": "C:\\Users\\thors\\Documents\\Claude\\openscad-mcp\\.venv\\Scripts\\python.exe",
|
||||
"args": ["C:\\Users\\thors\\Documents\\Claude\\openscad-mcp\\server.py"]
|
||||
},
|
||||
"cadquery": {
|
||||
"command": "C:\\Users\\thors\\Documents\\Claude\\cadquery\\.venv\\Scripts\\python.exe",
|
||||
"args": ["C:\\Users\\thors\\Documents\\Claude\\cadquery\\server.py"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 Claude Desktop neu starten
|
||||
|
||||
Nach dem Speichern der Config muss Claude Desktop **vollständig neu gestartet** werden.
|
||||
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:
|
||||
C:\Users\<Benutzername>\Documents\Claude\cadquery\.venv\Scripts\cq-editor.exe
|
||||
|
||||
# Alternativ über Python:
|
||||
.venv\Scripts\python -m cq_editor
|
||||
```
|
||||
|
||||
### Startskript (optional)
|
||||
|
||||
Für einfacheres Starten kann eine Datei `start-cq-editor.bat` im Projektverzeichnis
|
||||
angelegt werden:
|
||||
|
||||
```batch
|
||||
@echo off
|
||||
C:\Users\<Benutzername>\Documents\Claude\cadquery\.venv\Scripts\cq-editor.exe
|
||||
```
|
||||
|
||||
### Workflow mit CQ-editor
|
||||
|
||||
1. CQ-editor starten
|
||||
2. CadQuery-Code im Editor schreiben
|
||||
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 Desktop stehen drei Tools zur Verfügung:
|
||||
|
||||
#### `mcp__cadquery__render_stl`
|
||||
Führt CadQuery-Python-Code aus und exportiert eine STL-Datei.
|
||||
|
||||
```
|
||||
Parameter:
|
||||
code : str – CadQuery-Python-Code
|
||||
filename : str – Ausgabedateiname (Standard: "model.stl")
|
||||
```
|
||||
|
||||
#### `mcp__cadquery__preview_png`
|
||||
Exportiert eine SVG-Vorschau des Modells.
|
||||
|
||||
```
|
||||
Parameter:
|
||||
code : str – CadQuery-Python-Code
|
||||
filename : str – Ausgabedateiname (Standard: "preview.png")
|
||||
```
|
||||
|
||||
#### `mcp__cadquery__list_models`
|
||||
Listet alle STL-Dateien im Output-Verzeichnis 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
|
||||
|
||||
**Einfacher Quader:**
|
||||
```python
|
||||
import cadquery as cq
|
||||
|
||||
result = cq.Workplane("XY").box(30, 20, 10)
|
||||
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)
|
||||
```
|
||||
|
||||
**Parametrisches Modell:**
|
||||
```python
|
||||
import cadquery as cq
|
||||
|
||||
breite = 40
|
||||
hoehe = 20
|
||||
tiefe = 10
|
||||
radius = 3
|
||||
|
||||
result = (
|
||||
cq.Workplane("XY")
|
||||
.box(breite, tiefe, hoehe)
|
||||
.edges("|Z")
|
||||
.fillet(radius)
|
||||
)
|
||||
show_object(result)
|
||||
```
|
||||
|
||||
**Assembly (Baugruppe):**
|
||||
```python
|
||||
import cadquery as cq
|
||||
|
||||
box = cq.Workplane("XY").box(20, 20, 10)
|
||||
zylinder = cq.Workplane("XY").cylinder(15, 5)
|
||||
|
||||
asm = (
|
||||
cq.Assembly()
|
||||
.add(box, name="basis", loc=cq.Location((0, 0, 0)))
|
||||
.add(zylinder, name="zapfen", loc=cq.Location((0, 0, 10)))
|
||||
)
|
||||
show_object(asm)
|
||||
```
|
||||
|
||||
### 5.4 Output-Verzeichnis
|
||||
|
||||
STL-Dateien werden gespeichert in:
|
||||
```
|
||||
C:\Users\<Benutzername>\3d-models\
|
||||
```
|
||||
|
||||
Diesen Pfad kann man über die Umgebungsvariable `CADQUERY_OUTPUT_DIR` überschreiben.
|
||||
|
||||
---
|
||||
|
||||
## 6. Projektstruktur
|
||||
|
||||
```
|
||||
cadquery/
|
||||
├── .venv/ # Python Virtual Environment (nicht ins Git)
|
||||
├── 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: `C:\Users\<Benutzername>\3d-models\`
|
||||
- Schreibrechte auf das Verzeichnis prüfen
|
||||
|
||||
### Claude Desktop zeigt keine MCP-Tools
|
||||
|
||||
1. `claude_desktop_config.json` auf korrekte Pfade und JSON-Syntax prüfen
|
||||
2. Claude Desktop vollständig beenden (Taskleiste → Rechtsklick → Beenden)
|
||||
3. Claude Desktop neu starten
|
||||
|
||||
### 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.
|
||||
Reference in New Issue
Block a user