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 Desktop 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 Desktop	aktuell	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

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 Test-STL erzeugen

.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

C:\Users\thors\.claude\claude_desktop_config.json

3.2 CadQuery-Server eintragen

Aktueller Inhalt der Datei (bereits eingetragen):

{
  "mcpServers": {
    "cadquery": {
      "command": "C:\\Users\\thors\\Documents\\Claude\\cadquery\\.venv\\Scripts\\python.exe",
      "args":    ["C:\\Users\\thors\\Documents\\Claude\\cadquery\\server.py"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Hinweis: Backslashes müssen in JSON doppelt escapt werden (\\).

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

# 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:

@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):

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

Einfacher Quader:

import cadquery as cq

result = cq.Workplane("XY").box(30, 20, 10)
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)

Parametrisches Modell:

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):

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:

.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.