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.

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.

Related MCP server: FreeCAD MCP Server

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:

./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 (addon/FreeCADMCP) kopieren nach:

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:

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

3. Connector in Claude Desktop installieren

freecad-mcp-connector.mcpb aus den Releases laden und in Claude Desktop unter Einstellungen → Erweiterungen ins Fenster ziehen.

Einstellungen

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

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:

Werkzeuge

Selbst bauen

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:

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

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, Details in NOTICE.

Die 14 Werkzeuge stammen aus dem Paket 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:

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.