Skip to main content
Glama
FreeCAD MCP Connector

FreeCAD MCP Connector

by mario-2015

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

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:

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.

Available Tools

14 tools
create_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:

  1. Fetch shapes into local variables first (via execute_code on the GUI thread).

  2. Store intermediate results in a module-level Python variable (not in the FreeCAD document) so execute_code can read them later.

  3. Run the heavy computation via execute_code_async.

  4. 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

    A4/5.0

    Scored across 14 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      10
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Bridges 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.
      9
      37
      GNU Lesser General Public v2.1 or later
    • A
      license
      A
      quality
      D
      maintenance
      Enables to control FreeCAD from Claude Desktop through MCP, allowing CAD operations like creating and editing objects, taking screenshots, and executing Python code.
      11
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables Claude Desktop to control FreeCAD for 3D CAD modeling, including creating, editing, and deleting objects, executing Python code, and running FEM analyses.
      14
      MIT