# FreeCAD MCP Connector for Claude Desktop

Ein installierbarer Connector (`.mcpb`), der Claude mit einer laufenden FreeCAD-Instanz verbindet. Kein Bearbeiten von `claude_desktop_config.json` — Datei ins Erweiterungs-Fenster ziehen, fertig.

Claude kann damit Dokumente anlegen, Bauteile erzeugen und ändern, Python-Code direkt in FreeCAD ausführen, Teile aus der Parts Library einfügen, FEM-Analysen starten und sich die 3D-Ansicht als Screenshot ansehen.

![Aufbau eines Tischgestells, Bauteil für Bauteil](assets/aufbau.gif)

## Wie es funktioniert

```
Claude Desktop  ──stdio──►  Connector (MCP-Server)  ──XML-RPC :9875──►  FreeCAD + Addon
```

Der Connector allein reicht nicht: FreeCAD braucht das Addon **FreeCADMCP**, das den RPC-Server im laufenden FreeCAD bereitstellt. Beide Teile werden unten eingerichtet.

## Voraussetzungen

- FreeCAD 1.0 oder 1.1
- Claude Desktop in einer Version, die `.mcpb`-Erweiterungen unterstützt
- Python ≥ 3.12 (holt sich `uv` bei Bedarf selbst)

## Installation

### 1. FreeCAD-Addon installieren

macOS und Linux:

```bash
./install-freecad-addon.sh
```

Das Skript erkennt das FreeCAD-Benutzerverzeichnis, kopiert das Addon dorthin und schaltet auf Wunsch den automatischen Start des RPC-Servers ein.

Von Hand geht es auch — Addon aus [neka-nat/freecad-mcp](https://github.com/neka-nat/freecad-mcp) (`addon/FreeCADMCP`) kopieren nach:

| System | Zielverzeichnis |
| --- | --- |
| macOS (FreeCAD 1.1) | `~/Library/Application Support/FreeCAD/v1-1/Mod/` |
| Windows | `%APPDATA%\FreeCAD\Mod\` |
| Linux (1.1) | `~/.local/share/FreeCAD/v1-1/Mod/` |
| Linux (älter) | `~/.FreeCAD/Mod/` |

Danach **FreeCAD neu starten**. Ein bereits laufendes FreeCAD lädt das Addon nicht nach.

### 2. RPC-Server in FreeCAD starten

Workbench **MCP Addon** wählen, dann in der Toolbar **Start RPC Server**. Über **Toggle Auto Start** startet der Server künftig automatisch beim Programmstart.

Prüfen, ob er lauscht:

```bash
lsof -nP -iTCP:9875 -sTCP:LISTEN     # macOS/Linux
```

### 3. Connector in Claude Desktop installieren

`freecad-mcp-connector.mcpb` aus den [Releases](https://github.com/mario-2015/freecad-mcp-connector-for-claude-desktop/releases) laden und in Claude Desktop unter **Einstellungen → Erweiterungen** ins Fenster ziehen.

## Einstellungen

Beide Optionen sind nach der Installation im Erweiterungs-Dialog einstellbar.

| Einstellung | Standard | Bedeutung |
| --- | --- | --- |
| FreeCAD-Host | `localhost` | Adresse des Rechners mit FreeCAD. Für FreeCAD auf einem anderen Rechner dort zusätzlich **Remote Connections** aktivieren und die eigene IP freigeben. |
| Nur Text-Feedback | aus | Unterdrückt Screenshots der 3D-Ansicht. Spart deutlich Tokens, nimmt Claude aber die visuelle Kontrolle über das Ergebnis. |

## Arbeitsregeln und Vorlagen

Der Connector überträgt beim Handshake MCP-Instructions und registriert zusätzliche Prompts auf der Serverinstanz.

**Instructions** gelten ohne Auswahl für jede Aufgabe der Sitzung:

- Referenz auswerten, bevor Geometrie entsteht — Außenmaße allein determinieren keine Form
- Koordinatensystem definieren und Bauteilliste mit Positionen ausgeben, vor dem ersten Objekt
- Dokument direkt nach `create_document` speichern, danach nach jedem Bauteil
- Ein Bauteil pro Tool-Aufruf statt einem Sammelskript
- Keine nicht belegten Bauteile ergänzen (Streben, Sockel, Verrundungen)

**Prompts** erscheinen in Claude Desktop als Vorlagen:

| Vorlage | Zweck |
| --- | --- |
| `cad_bauauftrag` | Macht aus einer groben Idee einen präzisen Bauauftrag. Felder: Objekt, Referenz-URL, Maße, Besonderheiten. |
| `modell_pruefen` | Vergleicht das gebaute Modell mit der Vorlage und listet Abweichungen mit Ist- und Soll-Maß, ohne etwas zu ändern. |

## Werkzeuge

| Werkzeug | Zweck |
| --- | --- |
| `create_document`, `list_documents`, `reload_document` | Dokumente verwalten |
| `create_object`, `edit_object`, `delete_object` | Objekte erzeugen und ändern (Part, PartDesign, Draft, Sketch, FEM) |
| `get_objects`, `get_object` | Objekte samt Eigenschaften auslesen |
| `execute_code`, `execute_code_async` | Python direkt in FreeCAD ausführen |
| `get_view` | Screenshot der 3D-Ansicht |
| `get_parts_list`, `insert_part_from_library` | Parts Library durchsuchen und einfügen |
| `run_fem_analysis` | FEM-Analyse rechnen lassen |

## Selbst bauen

```bash
npm install -g @anthropic-ai/mcpb
mcpb validate manifest.json
mcpb pack . freecad-mcp-connector.mcpb
```

## Fehlersuche

### `Connection refused` bei jedem Tool-Aufruf

Auf Port 9875 lauscht kein Socket. Diagnose in dieser Reihenfolge:

```bash
pgrep -fl "Applications/FreeCAD.app"                    # Prozess vorhanden
lsof -nP -iTCP:9875 -sTCP:LISTEN                        # Port im LISTEN-Zustand
python3 -c "import xmlrpc.client;print(xmlrpc.client.ServerProxy('http://localhost:9875').ping())"
```

`Connection refused` ist eine TCP-Absage (`ECONNREFUSED`), kein Timeout. Ein blockierter oder im Hintergrund liegender Prozess erzeugt sie nicht — der Listener existiert dann schlicht nicht.

Die Fensterposition ist ohne Einfluss: Der XML-RPC-Server läuft in einem eigenen Thread und übergibt Aufgaben per Qt-Signal an den GUI-Thread. Einzige Ausnahme ist die Maustasten-Sperre in `gui_dispatch.py` — bei gedrückter Maustaste pausiert die Abarbeitung, damit MCP-Aufrufe eine laufende 3D-Navigation nicht unterbrechen.

Unter macOS beendet sich FreeCAD beim Schließen des Hauptfensters vollständig. Ein zuvor funktionierender Connector, der plötzlich `ECONNREFUSED` liefert, hat meist keinen Prozess mehr als Gegenstelle.

### Workbench fehlt in der Auswahlliste

`InitGui.py` wird ausschließlich beim Programmstart ausgewertet. Ein laufendes FreeCAD lädt ein neu kopiertes Addon nicht nach.

Registrierung prüfen — die Workbench heißt intern `FreeCADMCPAddonWorkbench` und erscheint im Menü unter ihrem `MenuText` „MCP Addon":

```python
import FreeCADGui
[w for w in FreeCADGui.listWorkbenches() if "MCP" in w]
```

Antwortet der RPC-Server, ist die Workbench zwangsläufig registriert — Autostart und `Gui.addWorkbench()` stehen in derselben `InitGui.py`.

Unter macOS zusätzlich den Pfad des laufenden Prozesses prüfen. Eine aus `AppTranslocation` gestartete Kopie liefert ein abweichendes `FreeCAD.getUserAppDataDir()` und findet `Mod/FreeCADMCP` nicht.

### Ausführungskontext von `execute_code`

Das Tool führt Python im FreeCAD-Prozess aus: keine Sandbox, keine Rechtetrennung, voller Zugriff mit der UID des angemeldeten Benutzers. Dateisystem, Netzwerk und Subprozesse sind erreichbar.

Der RPC-Server bindet standardmäßig auf `127.0.0.1`. Remote-Zugriff erfordert `remote_enabled` im Addon plus eine IP-Whitelist in `freecad_mcp_settings.json`.

## Lizenz und Herkunft

MIT — siehe [LICENSE](LICENSE), Details in [NOTICE](NOTICE).

Die 14 Werkzeuge stammen aus dem Paket [`freecad-mcp`](https://github.com/neka-nat/freecad-mcp) von **neka-nat** (MIT), ebenso das FreeCAD-Addon. Dieses Projekt ergänzt die Schichten darum herum und lässt den Server selbst unverändert:

| | `freecad-mcp` allein | mit diesem Connector |
| --- | --- | --- |
| **Installation** | `claude_desktop_config.json` von Hand um einen `mcpServers`-Eintrag ergänzen, Pfad zu `uvx` selbst richtig setzen | `.mcpb` ins Erweiterungs-Fenster ziehen |
| **Host / Text-Feedback** | als CLI-Argumente im JSON hinterlegt, Änderung = Datei editieren und neu starten | Felder im Erweiterungs-Dialog |
| **Versionsstand** | löst bei jedem Start die neueste passende Version auf | über mitgeliefertes `uv.lock` festgenagelt, auf jedem Rechner identisch |
| **Arbeitsregeln** | keine | MCP-Instructions, gelten in jeder Sitzung ohne Zutun |
| **Vorlagen** | eine (`asset_creation_strategy`) | zusätzlich `cad_bauauftrag` und `modell_pruefen` |
| **FreeCAD-Addon** | Repo klonen, Zielverzeichnis der eigenen FreeCAD-Version selbst ermitteln, kopieren | `install-freecad-addon.sh` ermittelt es und richtet auf Wunsch den Autostart ein |

Der praktische Unterschied liegt in den Instructions. Ohne sie beantwortet das Modell „Tisch, 180 × 80 × 90" mit vier Quadern und einer Platte, weil drei Außenmaße keine Form determinieren. Mit ihnen wertet es zuerst die Referenz aus, legt ein Koordinatensystem fest, zeigt eine Bauteilliste zur Kontrolle und baut erst danach — Bauteil für Bauteil, mit Speichern nach jedem Schritt.