FreeCAD mit OpenCode und MCP verwenden

Einleitung

FreeCAD ist zweifellos eine der leistungsfähigsten parametrischen CAD-Anwendungen überhaupt. Trotzdem kann es viel wiederholte Arbeit, die Suche nach Funktionen im Internet und eine ganze Menge Rückgängig-Schritte erfordern, ein Modell damit von Grund auf zu erstellen ... sehr viele davon!

Du wählst eine Arbeitsumgebung aus, erstellst ein Dokument, fügst Skizzen hinzu, setzt Constraints, erstellst Features, prüfst den Baum und wiederholst den Vorgang, bis das Ergebnis stimmt. Ein bisschen umständlich, oder?

Aber was wäre, wenn du das gewünschte Bauteil beschreiben und einen Coding-Agenten bitten könntest, es direkt in FreeCAD zu erstellen – ganz ähnlich wie beim Programmieren?

Das wäre ziemlich cool, findest du nicht?

Dann bist du hier genau richtig, denn genau das werden wir in dieser Anleitung erklären.

Das ist die Idee hinter dem FreeCAD-MCP-Server, einem Open-Source-Projekt, mit dem du FreeCAD mit einem MCP-kompatiblen KI-Client verbinden kannst, sodass wir es direkt über natürlichsprachliche Prompts steuern können!

Das Ziel ist nicht, CAD-Kenntnisse zu ersetzen oder generierte Geometrie blind zu akzeptieren, sondern die Interaktion zwischen Mensch und Maschine gesprächiger und programmierbarer zu machen. Wir können den Agenten bitten, ein Dokument zu erstellen, ein einfaches Teil zu erzeugen, den Objektbaum zu prüfen, eine Abmessung zu ändern oder zu erklären, warum ein Feature fehlgeschlagen ist – genau wie bei einem Gespräch mit einem Menschen!

Was wir brauchen

Zuerst beginnen wir mit einer Liste von allem, was wir für dieses kleine Projekt benötigen:

Am einfachsten ist es, FreeCAD und OpenCode auf demselben Computer auszuführen. In diesem Aufbau kann der MCP-Server die lokale Standardverbindung verwenden, und wir müssen FreeCAD nicht im Netzwerk freigeben oder komplizierte Konfigurationen bearbeiten.

Warum FreeCAD?

Okay, aber warum FreeCAD und nicht eine andere beliebte 3D-CAD-Lösung?

Ich habe mich einfach für FreeCAD entschieden, weil es vollständig quelloffen und kostenlos ist, ohne undurchsichtige Lizenzregeln oder seltsame Vorgaben zur Unternehmensgröße. Du möchtest ein 3D-Projekt für dich, deine Familie oder dein Unternehmen mit einer Million Mitarbeitenden erstellen? Kein Problem, dafür ist keine Lizenz erforderlich!

FreeCAD bietet uns alle Werkzeuge, die wir zum Erstellen präziser Teile, Baugruppen, technischer Zeichnungen und mehr benötigen, während Abmessungen, Skizzen und Beziehungen bearbeitbar bleiben.

Im Gegensatz zu einem einfachen Zeichenprogramm merkt sich FreeCAD, wie das Modell erstellt wurde. Wenn wir die Länge einer Skizze, die Position eines Lochs oder die Dicke eines Features ändern, kann der Rest des Modells diesen Beziehungen entsprechend aktualisiert werden, statt dass wir alles manuell neu zeichnen müssen!

FreeCAD organisiert seine Werkzeuge in verschiedenen Arbeitsumgebungen. Dadurch können wir genau die Features auswählen, die für die jeweilige Aufgabe sinnvoll sind, und der Erstellungsprozess wird deutlich einfacher und übersichtlicher.

Eine weitere sehr praktische Eigenschaft von FreeCAD ist, dass sich sein Verhalten durch Add-ons und Skripte erweitern lässt. Dadurch eignet es sich perfekt, um mit einem KI-Coding-Agenten zu experimentieren und gleichzeitig die Kontrolle über das Design und unsere Dateien zu behalten.

Warum OpenCode?

Für den Agenten habe ich mich für OpenCode entschieden.

OpenCode ist ein sehr beliebter Coding-Agent. Da es quelloffen ist, passt es hervorragend zu FreeCAD.

Mit den verfügbaren Modellen kann OpenCode natürlichsprachliche Anfragen verstehen, eine Abfolge von Aktionen planen und verbundene Tools verwenden, um eine Aufgabe zu erledigen. Du kannst OpenCode mit deinem bestehenden bevorzugten LLM oder KI-Abonnement wie GitHub Copilot verwenden oder es mit einer externen API-Plattform wie OpenRouter verbinden.

Anstatt das Terminal als Ort zu betrachten, an dem wir jeden Befehl perfekt eintippen müssen, können wir beschreiben, was wir erreichen möchten, und den Agenten bei der Auswahl der nächsten Schritte unterstützen lassen.

In unserem konkreten Fall bietet uns OpenCode eine gesprächige Möglichkeit, FreeCAD zu bitten, Dokumente zu erstellen, Modelle zu bauen, Objekte zu prüfen und klar zu erklären, wie diese Aufgaben erledigt wurden.

Wir können das gewünschte Ergebnis in einfachen Worten beschreiben, die Arbeit des Agenten überprüfen und um eine konkrete Änderung bitten, wenn etwas korrigiert werden muss. OpenCode kann uns außerdem die Antworten der Tools zurückgeben. So können wir den Agenten bitten, den Dokumentbaum zu prüfen, Abmessungen zu verifizieren oder vor der nächsten Entscheidung einen Screenshot aufzunehmen.

Da OpenCode quelloffen ist, können wir sein Projekt untersuchen, es lokal konfigurieren und es mit Tools wie dem FreeCAD-MCP-Server verbinden, statt uns nur auf einen geschlossenen, unveränderlichen Ablauf zu verlassen.

Warum einen MCP-Server verwenden?

Das Model Context Protocol, kurz MCP, gibt einem KI-Client eine standardisierte Möglichkeit, externe Tools zu entdecken und aufzurufen, die Kontext für LLM-Aufrufe bereitstellen können.

Anstatt FreeCAD über Bildschirmklicks und Mausbewegungen zu steuern, kann OpenCode die vom FreeCAD-MCP-Server bereitgestellten Tools direkt aufrufen. Dadurch kann der Agent die CAD-Software über eine KI-freundliche API steuern.

Das FreeCAD-MCP-Projekt, das wir in dieser Anleitung verwenden, stellt unter anderem Tools für folgende Aufgaben bereit:

Dadurch erhält der Agent eine nützliche Rückkopplungsschleife. Er kann eine Änderung vornehmen, das Ergebnis prüfen und seine nächste Aktion anpassen, statt nur Code zu schreiben, den wir manuell einfügen müssen. Ziemlich praktisch, oder?

1. FreeCAD MCP herunterladen

Okay, als Erstes laden wir das offizielle Repository herunter, das vom großartigen neka-nat erstellt wurde.

Öffne dazu ein Terminal, wechsle in ein Verzeichnis deiner Wahl und führe den folgenden Befehl aus:

$git clone https://github.com/neka-nat/freecad-mcp.git

Das Repository enthält sowohl den Python-MCP-Server als auch das FreeCAD-Addon. Bewahre das Repository an einem stabilen Ort auf, da OpenCode beim Start des Servers seinen Pfad benötigt.

Unter Windows empfehle ich, es in deinem Documents-Ordner aufzubewahren. Zum Beispiel könntest du folgenden Pfad verwenden:

C:\Users\YourName\Documents\freecad-mcp

Wenn du einen anderen Ort verwendest, ist das kein Problem. Wir müssen später in der OpenCode-Konfiguration nur den Beispielpfad ersetzen.

2. FreeCAD-Addon installieren

Der MCP-Server benötigt außerdem ein in FreeCAD installiertes Add-on. Das offizielle Repository enthält alles, was wir brauchen, im Verzeichnis addon/FreeCADMCP.

Unter Windows verwendet FreeCAD 1.1 das folgende versionsabhängige Add-on-Verzeichnis:

C:\Users\YourName\AppData\Roaming\FreeCAD\v1-1\Mod\FreeCADMCP

Um das Add-on zu installieren, öffne das geklonte Repository und kopiere den Ordner FreeCADMCP aus addon.

Füge ihn anschließend in den folgenden FreeCAD-Ordner ein. Erstelle den Ordner Mod, falls er noch nicht existiert:

C:\Users\YourName\AppData\Roaming\FreeCAD\v1-1\Mod

Kurz gesagt: Kopiere den folgenden Ordner:

C:\Users\YourName\Documents\freecad-mcp\addon\FreeCADMCP

in diesen Ordner:

C:\Users\YourName\AppData\Roaming\FreeCAD\v1-1\Mod

Ältere FreeCAD-Versionen verwenden möglicherweise den Ordner C:\Users\YourName\AppData\Roaming\FreeCAD\Mod für Add-ons. Verwende das Verzeichnis, das zum versionsabhängigen Ordner deiner FreeCAD-Installation passt.

Starte FreeCAD nach dem Kopieren des Add-ons neu, falls es bereits geöffnet war. Das Repository dokumentiert auch die Add-on-Verzeichnisse für Linux und macOS, falls du ein anderes Betriebssystem verwendest.

MCP-Addon-Arbeitsumgebung auswählen

Öffne nach dem Neustart von FreeCAD die Auswahl der Arbeitsumgebungen und wähle MCP Addon. Nun sollte die FreeCAD-MCP-Symbolleiste oder das entsprechende Menü sichtbar sein.

Klicke auf Start RPC Server, um die lokale Brücke zu starten. Der von OpenCode gestartete MCP-Server verwendet diese Brücke, um mit FreeCAD zu kommunizieren.

Der RPC-Server muss normalerweise bei jedem Start von FreeCAD gestartet werden. Wenn er automatisch starten soll, öffne das Menü FreeCAD MCP und aktiviere Auto-Start Server. Die Einstellung wird vom Add-on gespeichert und bleibt über mehrere Sitzungen hinweg erhalten.

3. OpenCode installieren

Als Nächstes installieren wir OpenCode.

Wir können OpenCode mit dem offiziellen Installer und dem folgenden Bash-Befehl installieren:

$curl -fsSL https://opencode.ai/install | bash

Wenn du wie ich lieber npm verwendest, kannst du stattdessen den folgenden Befehl ausführen:

$npm i -g opencode-ai

Öffne nach Abschluss der Installation ein neues Terminal, damit der Befehl opencode in deinem PATH verfügbar ist. Prüfen wir, ob er funktioniert:

$opencode --version

Du musst außerdem einen KI-Anbieter konfigurieren, bevor OpenCode als Coding-Agent arbeiten kann. Wenn du OpenCode zum ersten Mal installierst, findest du in der OpenCode-Dokumentation Hinweise zur Einrichtung des Anbieters.

4. OpenCode konfigurieren

OpenCode liest seine Projektkonfiguration aus einer Datei opencode.json oder opencode.jsonc. Wir können diese Datei im Stammverzeichnis eines Projekts ablegen oder die globale OpenCode-Konfiguration verwenden, wenn FreeCAD überall verfügbar sein soll.

Unter Windows befindet sich die globale Konfigurationsdatei normalerweise hier:

C:\Users\YourName\.config\opencode\opencode.json

Falls das Verzeichnis oder die Datei noch nicht existiert, erstelle sie, bevor du die Konfiguration hinzufügst.

Erstelle oder bearbeite nun die OpenCode-Konfiguration und füge den FreeCAD-MCP-Server wie unten gezeigt unter dem Schlüssel mcp hinzu:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "freecad": {
      "type": "local",
      "command": [
        "uv",
        "--directory",
        "C:\\Users\\YourName\\Documents\\freecad-mcp",
        "run",
        "freecad-mcp"
      ],
      "enabled": true
    }
  }
}

Ersetze C:\\Users\\YourName\\Documents\\freecad-mcp durch den tatsächlichen Pfad zu deinem Klon. JSON-Pfade verwenden maskierte Backslashes. Ein Windows-Pfad wie C:\Users\YourName\Documents\freecad-mcp muss daher innerhalb der JSON-Datei als C:\\Users\\YourName\\Documents\\freecad-mcp geschrieben werden.

5. OpenCode starten

Bevor wir OpenCode starten, sollten wir bestätigen, dass FreeCAD geöffnet ist, die Arbeitsumgebung MCP Addon ausgewählt wurde und der RPC-Server läuft.

Wenn alles passt, starte OpenCode aus dem Verzeichnis, in dem sich die Konfiguration befindet:

$opencode

OpenCode sollte den freecad-MCP-Server beim Start erkennen. Wenn der Server nicht erscheint, überprüfe den Pfad in opencode.json, bestätige, dass uv in deinem PATH verfügbar ist, und prüfe den Status des OpenCode-MCP-Servers.

Wir können OpenCode auch mit einem einfachen Prompt fragen, ob es auf den FreeCAD-MCP zugreifen kann:

Do you have access to the FreeCAD MCP?

Beginne nicht mit einem komplexen CAD-Projekt. Ein kleiner Verbindungstest macht es viel einfacher herauszufinden, ob ein späteres Problem von OpenCode, dem MCP-Server oder FreeCAD selbst verursacht wird.

Wenn die Antwort positiv ist, herzlichen Glückwunsch! OpenCode ist nun erfolgreich mit dem FreeCAD-MCP verbunden.

6. Erstes Projekt erstellen

Okay, machen wir mit einer etwas detaillierteren Anfrage weiter:

Use the freecad MCP server to create a new document named AgentTest, then list the objects in the document.

Der Agent sollte create_document und anschließend get_objects aufrufen. Abhängig von den Servereinstellungen kann die Antwort außerdem einen Screenshot der FreeCAD-Ansicht enthalten.

Wenn die Anfrage erfolgreich ist, hast du die gesamte Verbindungskette bestätigt:

Großartig! Speichere das Dokument jetzt manuell oder bitte den Agenten, es mit FreeCAD-Python zu speichern. Wenn du dieses erste Testdokument aufbewahrst, ist es später bei der Fehlersuche hilfreich.

7. Einfaches parametrisches Teil erstellen

Sobald die Verbindung funktioniert, können wir den Agenten bitten, ein kleines Modell mit konkreten Abmessungen zu erstellen. Eine einfache Platte mit vier Löchern ist ein gutes erstes Projekt, weil die Geometrie eindeutig und leicht zu prüfen ist.

Zum Beispiel können wir einen Prompt wie diesen verwenden:

Use the freecad MCP tools to create a new document containing a parametric rectangular plate.

Requirements:
- The plate should be 100 mm long, 60 mm wide, and 8 mm thick.
- Add four through-holes with a diameter of 6 mm.
- Place the holes symmetrically, 10 mm from the nearest two edges.
- Use meaningful object names.
- Recompute the document and report the objects and final dimensions.
- Do not overwrite any existing document.

Die genaue Umsetzung bleibt dem Agenten überlassen. Er kann Part-Primitives erstellen, eine Skizze und einen Pad verwenden oder FreeCAD-Python ausführen, das die Form erstellt. Wichtig ist, die Abmessungen, Constraints, Erwartungen an die Benennung und Sicherheitsgrenzen klar anzugeben.

Ergebnis prüfen

Nachdem das Modell erstellt wurde, bitten wir den Agenten, es zu prüfen, statt sofort ein weiteres Feature anzufordern:

Inspect the current FreeCAD document with the freecad MCP tools. List every object, its type, its dimensions, and any visible errors. Take an isometric view screenshot if available.

Hier wird der MCP-Workflow nützlicher als eine einmalige Codegenerierung. Wir können den Bericht des Agenten mit dem FreeCAD-Baum und dem Ansichtsfenster vergleichen und anschließend eine gezielte Korrektur anfordern.

Wenn die Löcher beispielsweise nicht an der richtigen Stelle liegen, können wir Folgendes sagen:

The plate looks correct, but the holes are not symmetric around the center. Inspect the model and move only the hole locations so the four hole centers are 10 mm from the corresponding edges. Preserve the plate thickness and hole diameter.

Formuliere Änderungswünsche präzise. Wenn du den Agenten bittest, etwas „besser aussehen“ zu lassen, gibst du ihm zu viel Freiheit, und das Ergebnis wird schwieriger zu überprüfen.

8. Mit FreeCAD-Python arbeiten

Mit dem Tool execute_code kann der Agent Python innerhalb von FreeCAD ausführen. Das ist eine wirklich leistungsfähige Funktion, weil FreeCAD einen großen Teil seiner Modellierungsfunktionen über Python bereitstellt. Gleichzeitig bedeutet das, dass wir den generierten Code prüfen sollten, bevor wir wichtige Änderungen zulassen.

Beginnen wir mit einer sicheren Anfrage zur Untersuchung:

Use execute_code only to inspect the active document. Return the document name and a list of object names and types. Do not create, delete, or modify anything.

Bei einer kontrollierten Modellierungsaufgabe solltest du den Agenten zuerst die geplanten Vorgänge erklären lassen:

Before executing code, describe the FreeCAD objects and operations you plan to use to create the plate. Wait for confirmation before modifying the document.

Dieser zusätzliche Schritt ist nützlich, wenn wir die API kennenlernen oder mit einem Modell arbeiten, das wichtige Konstruktionsarbeit enthält.

Denke daran, dass FreeCAD-Operationen Abhängigkeiten haben können. Das Löschen oder Ändern eines Objekts kann sich auf Skizzen, Pads, Schnitte oder nachgelagerte Features auswirken. Ein Modell, das in einem Screenshot korrekt aussieht, kann trotzdem fragile oder falsche parametrische Beziehungen enthalten.

Fehlerbehebung

Wenn etwas fehlschlägt, hilft die folgende kurze Checkliste:

Das FreeCAD-MCP-Projekt weist darauf hin, dass GUI-Operationen nicht immer sicher zwangsweise abgebrochen werden können. Wenn eine GUI-Operation hängen bleibt, kann das Senden weiterer GUI-Anfragen die Situation verschlimmern. Prüfe den RPC-Status und starte FreeCAD bei Bedarf neu.

Wenn execute_code beim Erstellen eines FeaturePython-Objekts eine Ausnahme auslöst, prüfe das neue Objekt, bevor du versuchst, es zu ändern oder zu löschen. Bei einem teilweise erstellten Objekt ist der erwartete Proxy möglicherweise nicht installiert.

Praktische Hinweise

Ein KI-Coding-Agent ist am nützlichsten, wenn wir ihn als fähigen Mitarbeiter betrachten, dessen Arbeit überprüft werden muss. Gib ihm messbare Anforderungen, bitte ihn, sein Ergebnis zu prüfen, und halte Änderungen klein genug, um sie rückgängig machen zu können.

Für wiederholbare Aufgaben solltest du Abmessungen und Constraints beschreiben, statt nur das Aussehen zu nennen. „Erstelle eine 100 mm lange und 60 mm breite Platte mit vier 6-mm-Löchern“ ist viel nützlicher als „Erstelle eine kleine Montageplatte“.

Außerdem ist es eine gute Gewohnheit, vor größeren Änderungen Versionen unserer FreeCAD-Dateien zu speichern. Parametrische Modelle können versteckte Abhängigkeiten enthalten, und eine scheinbar kleine Änderung kann ein späteres Feature ungültig machen.

Denke zum Schluss daran, dass generiertes CAD nicht automatisch sicher für die Fertigung ist. Prüfe Einheiten, Toleranzen, Wandstärken, Befestigungsabstände, Materialannahmen und Exporteinstellungen selbst. Der Agent kann den Designprozess beschleunigen, aber die technische Verantwortung bleibt bei der Person, die das Modell freigibt.

Fazit

Damit sind wir am Ende dieser Reise angekommen! FreeCAD MCP ermöglicht es, eine laufende FreeCAD-Sitzung mit einem MCP-kompatiblen Agenten zu verbinden. Mit OpenCode können wir eine Modellierungsaufgabe in natürlicher Sprache beschreiben, den Agenten FreeCAD-Objekte erstellen oder ändern lassen, das Ergebnis prüfen und mit gezielten Anweisungen weiterarbeiten.

Hier ist eine kurze Zusammenfassung dessen, was wir gemacht haben:

Weitere Beispiele und die neuesten Installationshinweise findest du im FreeCAD-MCP-Repository und in der OpenCode-MCP-Dokumentation.

Wenn dein Verbindungstest funktioniert hat und der Agent dein erstes Teil erstellt hat, herzlichen Glückwunsch! Du hast jetzt eine gesprächige Brücke zwischen OpenCode und FreeCAD und kannst mit deinen eigenen parametrischen Modellen experimentieren!

Halte FreeCAD, das FreeCAD-MCP-Repository, OpenCode und uv aktuell, damit die Einrichtung zuverlässig funktioniert. Speichere vor wichtigen Änderungen eine Kopie deines Modells und überprüfe generierte Geometrie immer, bevor du sie in einem echten Projekt verwendest.

Wenn du praktische Open-Source-Projekte wie dieses magst, interessiert dich vielleicht auch unsere Anleitung zur Einrichtung von Pi-hole und Mullvad auf einem Raspberry Pi für einen netzwerkweiten Datenschutz oder unsere Anleitung zur Verwendung der mobilen Mullvad-VPN-App, wenn du einzelne Geräte unterwegs schützen möchtest!

Damit sind wir für heute fertig! Ich hoffe, dir hat diese Anleitung gefallen, und wir sehen uns hoffentlich bald wieder!