FreeCAD MCP Connector
This server connects Claude Desktop to a running FreeCAD instance via XML-RPC, enabling AI-driven 3D CAD modeling, document management, Python scripting, parts library access, and FEM structural analysis.
Document Management — Create, list, and reload FreeCAD documents (create_document, list_documents, reload_document).
Object Creation & Editing — Create new objects (Part, PartDesign, Draft, Sketch, FEM — boxes, cylinders, circles, bodies, analyses, constraints, materials, meshes), edit existing ones, and delete objects; each with configurable properties, placement, rotation, and color.
Inspection — List and get all objects in a document, or fetch a single object and its properties.
Python Execution — Run arbitrary Python code directly inside FreeCAD: execute_code on the GUI thread (full document/GUI access) and execute_code_async for long-running background computations that don't touch the document or GUI (e.g., heavy OCCT geometry calculations).
3D View Screenshots — Capture the view in multiple orientations (Isometric, Front, Top, Right, Back, Left, Bottom, Dimetric, Trimetric), with adjustable width/height and optional focus object.
Parts Library — Search the parts library, list all available parts, and insert parts into the active document.
FEM Analysis — Run CalculiX on a FEM analysis container, returning max von Mises stress, max/min displacement, node count, and the working directory.
Token/Visual Control — Nearly every tool supports include_screenshot and view_name to control when visual feedback is returned for token efficiency.
Integrates with a running FreeCAD instance, providing tools to create and modify documents and objects, execute Python code directly in FreeCAD, insert parts from the Parts Library, run FEM analyses, and capture screenshots of the 3D view.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@FreeCAD MCP Connector Create a new document and add a cylinder with diameter 40mm and height 60mm."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 + AddonDer 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ütztPython ≥ 3.12 (holt sich
uvbei Bedarf selbst)
Installation
1. FreeCAD-Addon installieren
macOS und Linux:
./install-freecad-addon.shDas 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) |
|
Windows |
|
Linux (1.1) |
|
Linux (älter) |
|
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/Linux3. 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 |
| 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_documentspeichern, danach nach jedem BauteilEin 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 |
| Macht aus einer groben Idee einen präzisen Bauauftrag. Felder: Objekt, Referenz-URL, Maße, Besonderheiten. |
| Vergleicht das gebaute Modell mit der Vorlage und listet Abweichungen mit Ist- und Soll-Maß, ohne etwas zu ändern. |
Werkzeuge
Werkzeug | Zweck |
| Dokumente verwalten |
| Objekte erzeugen und ändern (Part, PartDesign, Draft, Sketch, FEM) |
| Objekte samt Eigenschaften auslesen |
| Python direkt in FreeCAD ausführen |
| Screenshot der 3D-Ansicht |
| Parts Library durchsuchen und einfügen |
| FEM-Analyse rechnen lassen |
Selbst bauen
npm install -g @anthropic-ai/mcpb
mcpb validate manifest.json
mcpb pack . freecad-mcp-connector.mcpbFehlersuche
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:
| mit diesem Connector | |
Installation |
|
|
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 |
Arbeitsregeln | keine | MCP-Instructions, gelten in jeder Sitzung ohne Zutun |
Vorlagen | eine ( | zusätzlich |
FreeCAD-Addon | Repo klonen, Zielverzeichnis der eigenen FreeCAD-Version selbst ermitteln, kopieren |
|
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.
Available Tools
14 toolscreate_documentA
Create a new document in FreeCAD.
Args: name: The name of the document to create.
Returns: A message indicating the success or failure of the document creation.
Examples:
If you want to create a document named "MyDocument", you can use the following data.
json { "name": "MyDocument" }
Inputs: name (required).
create_objectA
Create a new object in FreeCAD. Object type is starts with "Part::" or "Draft::" or "PartDesign::" or "Fem::".
Args: doc_name: The name of the document to create the object in. obj_type: The type of the object to create (e.g. 'Part::Box', 'Part::Cylinder', 'Draft::Circle', 'PartDesign::Body', etc.). obj_name: The name of the object to create. obj_properties: The properties of the object to create. include_screenshot: Whether to return a screenshot of the model (default True). Set to False to save tokens when visual feedback is not needed, e.g. for intermediate steps in a longer sequence of changes. view_name: The view orientation of the returned screenshot (default "Isometric"). Pick the view that best shows the change being made.
Returns: A message indicating the success or failure of the object creation and a screenshot of the object.
Examples:
If you want to create a cylinder with a height of 30 and a radius of 10, you can use the following data.
json { "doc_name": "MyCylinder", "obj_name": "Cylinder", "obj_type": "Part::Cylinder", "obj_properties": { "Height": 30, "Radius": 10, "Placement": { "Base": { "x": 10, "y": 10, "z": 0 }, "Rotation": { "Axis": { "x": 0, "y": 0, "z": 1 }, "Angle": 45 } }, "ViewObject": { "ShapeColor": [0.5, 0.5, 0.5, 1.0] } } }
If you want to create a circle with a radius of 10, you can use the following data.
```json
{
"doc_name": "MyCircle",
"obj_name": "Circle",
"obj_type": "Draft::Circle",
}
```
If you want to create a FEM analysis, you can use the following data.
```json
{
"doc_name": "MyFEMAnalysis",
"obj_name": "FemAnalysis",
"obj_type": "Fem::AnalysisPython",
}
```
If you want to create a FEM constraint, you can use the following data.
```json
{
"doc_name": "MyFEMConstraint",
"obj_name": "FemConstraint",
"obj_type": "Fem::ConstraintFixed",
"analysis_name": "MyFEMAnalysis",
"obj_properties": {
"References": [
{
"object_name": "MyObject",
"face": "Face1"
}
]
}
}
```
If you want to create a FEM mechanical material, you can use the following data.
```json
{
"doc_name": "MyFEMAnalysis",
"obj_name": "FemMechanicalMaterial",
"obj_type": "Fem::MaterialCommon",
"analysis_name": "MyFEMAnalysis",
"obj_properties": {
"Material": {
"Name": "MyMaterial",
"Density": "7900 kg/m^3",
"YoungModulus": "210 GPa",
"PoissonRatio": 0.3
}
}
}
```
If you want to create a FEM mesh, you can use the following data.
The `Shape` property is required (legacy `Part` is also accepted).
On FreeCAD 1.x the size limits are `CharacteristicLengthMax/Min`;
the legacy `ElementSizeMax/Min` keys are also accepted.
```json
{
"doc_name": "MyFEMMesh",
"obj_name": "FemMesh",
"obj_type": "Fem::FemMeshGmsh",
"analysis_name": "MyFEMAnalysis",
"obj_properties": {
"Shape": "MyObject",
"CharacteristicLengthMax": 10,
"CharacteristicLengthMin": 0.1
}
}
```
Inputs: doc_name (required), obj_name (required), obj_type (required), view_name, +3 more.
delete_objectA
Delete an object in FreeCAD.
Args: doc_name: The name of the document to delete the object from. obj_name: The name of the object to delete. include_screenshot: Whether to return a screenshot of the model (default True). Set to False to save tokens when visual feedback is not needed, e.g. for intermediate steps in a longer sequence of changes. view_name: The view orientation of the returned screenshot (default "Isometric"). Pick the view that best shows the change being made.
Returns: A message indicating the success or failure of the object deletion and a screenshot of the object.
Inputs: doc_name (required), obj_name (required), view_name, include_screenshot.
edit_objectB
Edit an object in FreeCAD.
This tool is used when the create_object tool cannot handle the object creation.
Args: doc_name: The name of the document to edit the object in. obj_name: The name of the object to edit. obj_properties: The properties of the object to edit. include_screenshot: Whether to return a screenshot of the model (default True). Set to False to save tokens when visual feedback is not needed, e.g. for intermediate steps in a longer sequence of changes. view_name: The view orientation of the returned screenshot (default "Isometric"). Pick the view that best shows the change being made.
Returns: A message indicating the success or failure of the object editing and a screenshot of the object.
Inputs: doc_name (required), obj_name (required), obj_properties (required), view_name, +1 more.
execute_codeA
Execute arbitrary Python code in FreeCAD.
Args: code: The Python code to execute. include_screenshot: Whether to return a screenshot of the model (default True). Set to False to save tokens when the code does not change the model's appearance, e.g. analytical or computational scripts whose result is printed output, or intermediate steps in a longer sequence of changes. view_name: The view orientation of the returned screenshot (default "Isometric"). Pick the view that best shows the change being made.
Returns: A message indicating the success or failure of the code execution, the output of the code execution, and a screenshot of the object.
Inputs: code (required), view_name, include_screenshot.
execute_code_asyncA
Execute Python code in FreeCAD without waiting for completion.
Use this ONLY for long-running background computations that do NOT touch the FreeCAD GUI or mutate the FreeCAD document tree directly.
This tool runs the submitted code in a background thread and returns immediately. Because it does not run on FreeCAD's main GUI thread, the code must NOT call FreeCADGui APIs, manipulate the active view or selection, create or edit document objects, change object properties, call doc.recompute(), or save documents.
For code that touches FreeCAD documents, document objects, FreeCADGui, the active view, selection, recompute, or save operations, use execute_code instead. execute_code runs on the FreeCAD GUI thread and is the safe default for normal FreeCAD automation.
Use execute_code_async only for background-safe work such as long-running pure OCCT geometry calculations (e.g. fuse/cut/loft on already-fetched shapes) or other CPU-bound computations that do not interact with the document or GUI.
Typical usage pattern:
Fetch shapes into local variables first (via execute_code on the GUI thread).
Store intermediate results in a module-level Python variable (not in the FreeCAD document) so execute_code can read them later.
Run the heavy computation via execute_code_async.
After the expected computation time has elapsed, apply results to the document via execute_code (which runs on the GUI thread).
Args: code: Background-safe Python code to execute.
Returns: A message confirming that background execution has started.
Inputs: code (required).
get_objectA
Get an object from a document. You can use this tool to get the properties of an object to see what you can check or edit.
Args: doc_name: The name of the document to get the object from. obj_name: The name of the object to get. include_screenshot: Whether to return a screenshot of the document (default True). Set to False to save tokens when only the object data is needed. view_name: The view orientation of the returned screenshot (default "Isometric").
Returns: The object and a screenshot of the object.
Inputs: doc_name (required), obj_name (required), view_name, include_screenshot.
get_objectsA
Get all objects in a document. You can use this tool to get the objects in a document to see what you can check or edit.
Args: doc_name: The name of the document to get the objects from. include_screenshot: Whether to return a screenshot of the document (default True). Set to False to save tokens when only the object data is needed. view_name: The view orientation of the returned screenshot (default "Isometric").
Returns: A list of objects in the document and a screenshot of the document.
Inputs: doc_name (required), view_name, include_screenshot.
get_parts_listB
Get the list of parts in the parts library addon.
Inputs: no named parameters.
get_viewA
Get a screenshot of the active view.
Args: view_name: The name of the view to get the screenshot of. The following views are available: - "Isometric" - "Front" - "Top" - "Right" - "Back" - "Left" - "Bottom" - "Dimetric" - "Trimetric" width: The width of the screenshot in pixels. If not specified, uses the viewport width. height: The height of the screenshot in pixels. If not specified, uses the viewport height. focus_object: The name of the object to focus on. If not specified, fits all objects in the view.
Returns: A screenshot of the active view.
Inputs: view_name (required), width, height, focus_object.
insert_part_from_libraryA
Insert a part from the parts library addon.
Args: relative_path: The relative path of the part to insert. include_screenshot: Whether to return a screenshot of the model (default True). Set to False to save tokens when visual feedback is not needed, e.g. for intermediate steps in a longer sequence of changes. view_name: The view orientation of the returned screenshot (default "Isometric"). Pick the view that best shows the change being made.
Returns: A message indicating the success or failure of the part insertion and a screenshot of the object.
Inputs: relative_path (required), view_name, include_screenshot.
list_documentsA
Get the list of open documents in FreeCAD.
Returns: A list of document names.
Inputs: no named parameters.
reload_documentA
Close and re-open a document to pick up external file changes.
Use this AFTER the document's .FCStd file has been modified by
something outside of FreeCAD's GUI process — for example, a
headless freecadcmd script that edited and saved the file. The
open GUI document is otherwise unaware of on-disk changes; this
tool closes the stale in-memory copy and reopens the file from
disk so the GUI shows current geometry.
Args:
doc_name: The name of the open document to reload. Must match
the name shown by list_documents.
Returns: A message confirming the document was reloaded, or describing the failure (document not loaded, no associated file, etc).
Examples:
json { "doc_name": "chassis" }
Inputs: doc_name (required).
run_fem_analysisA
Run the CalculiX solver on an existing Fem::FemAnalysis container and return summary results.
Prerequisites in the document:
A Part-derived solid (e.g. Part::Box, PartDesign::Body) acting as the geometry.
A Fem::AnalysisPython container created via
create_object.A Fem::MaterialCommon assigned to the geometry, added to the analysis.
A Fem::FemMeshGmsh referencing the geometry, added to the analysis (the mesh is generated automatically when created via
create_object).At least one Fem::ConstraintFixed and one Fem::ConstraintForce (or ConstraintPressure) bound to faces of the geometry, added to the analysis.
A SolverCcxTools is auto-created if the analysis has none.
The solver runs synchronously on the FreeCAD GUI thread and blocks all other RPC calls for its duration; do not fan out parallel requests.
Returns max von Mises stress (MPa), max/min displacement (mm), node count, and the working directory CalculiX wrote to. On failure, returns the prerequisite-check or solver error along with the working directory for triage.
Args: doc_name: Name of the FreeCAD document. analysis_name: Name of the Fem::AnalysisPython object. timeout: Seconds to wait for the solver (default 600). include_screenshot: Whether to return a screenshot of the model (default True). Set to False to save tokens when only the numeric results are needed. view_name: The view orientation of the returned screenshot (default "Isometric").
Inputs: doc_name (required), analysis_name (required), timeout, view_name, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool targets a distinct resource or action: document management (create/list/reload), object CRUD (create/get/edit/delete), code execution (sync vs async), viewing, parts library (list/insert), and FEM analysis. Even execute_code vs execute_code_async are clearly separated by threading model and intended use.
All tool names follow a consistent verb_noun pattern in snake_case (create_object, get_objects, delete_object, list_documents, run_fem_analysis). No mixed conventions or vague verbs; the naming is predictable and readable.
14 tools is well within the ideal 3-15 range and appropriate for the broad scope of FreeCAD automation. Each tool earns its place without excessive fragmentation or unnecessary convergence.
Core CRUD for documents and objects is fully covered, along with parts library and FEM analysis execution. Minor gaps exist, such as no explicit save_document or close_document tools, but these are easily worked around via execute_code, so the surface is largely complete.
Maintenance
Related MCP Connectors
CAD in ChatGPT and Claude: editable parts, STEP/STL/drawings, in-chat 3D, automatic checks.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables control of FreeCAD CAD software from Claude Desktop through natural language commands. Supports creating, editing, and managing 3D objects, executing Python code, and generating screenshots of designs.10MIT
- AlicenseAqualityDmaintenanceBridges Claude with a live FreeCAD instance to provide deep access to runtime state, document structure, and shape topology. It enables AI-assisted CAD work, sketch diagnostics, and development debugging through direct interaction with FreeCAD's internal data and viewport.937GNU Lesser General Public v2.1 or later
- AlicenseAqualityDmaintenanceEnables to control FreeCAD from Claude Desktop through MCP, allowing CAD operations like creating and editing objects, taking screenshots, and executing Python code.111MIT
- AlicenseAqualityDmaintenanceEnables Claude Desktop to control FreeCAD for 3D CAD modeling, including creating, editing, and deleting objects, executing Python code, and running FEM analyses.14MIT