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.

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:

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:

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.

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

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:

	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.