Skip to main content
Glama
FreeCAD MCP for Codex

FreeCAD MCP for Codex

by hashbolic

FreeCAD MCP for Codex

This local Codex plugin exposes a compact typed MCP surface for FreeCAD 1.1.x on Windows. It connects to the bundled Robust MCP Bridge over XML-RPC by default and can also run with the embedded bridge when launched by FreeCAD's Python 3.11 runtime.

The bridge implementation and FreeCAD addon are derived from spkane/freecad-addon-robust-mcp-server under its MIT license. See LICENSE-CODE and UPSTREAM-NOTICE.md.

Configuration

Set FREECAD_MODE=xmlrpc (default), FREECAD_XMLRPC_PORT=9875, and start the bundled addon inside FreeCAD. FREECAD_ALLOW_EXECUTE_PYTHON=true is required for the controlled escape hatch; it is disabled by default.

Related MCP server: FreeCAD Robust MCP Server

Start the bridge in FreeCAD

The Codex plugin is the MCP client. FreeCAD also needs the bundled Robust MCP Bridge workbench running; installing the Codex plugin alone does not start the FreeCAD-side server.

  1. Install the addon folder freecad-addon/RobustMCPBridge into FreeCAD's user Mod directory. For FreeCAD 1.1 on Windows, use %APPDATA%\FreeCAD\v1-1\Mod\RobustMCPBridge. Create the Mod directory if it does not exist, then copy the whole RobustMCPBridge folder there.

  2. Restart FreeCAD so it loads the workbench.

  3. In the workbench selector, choose Robust MCP Bridge.

  4. Click Start MCP Bridge in its toolbar, or run Robust MCP Bridge → Start MCP Bridge from the menu.

  5. The default Codex connection uses XML-RPC at localhost:9875. The workbench status command or status-bar indicator should show the bridge as running.

  6. In Codex, call freecad_health; it should report connected: true. If the MCP server was started before FreeCAD, restart the FreeCAD MCP server from Codex after starting the bridge.

To start the bridge automatically with FreeCAD, open Edit → Preferences → Robust MCP Bridge, enable Auto-start bridge when FreeCAD launches, and apply the setting. Auto-start is off by default. The same preferences page lets you change the XML-RPC port; keep it at 9875 unless FREECAD_XMLRPC_PORT in the Codex MCP configuration is changed to the same value.

For a quick local port check in PowerShell, run:

Test-NetConnection 127.0.0.1 -Port 9875

The bridge listens on localhost. Do not expose its ports to other machines.

The MCP server intentionally starts even when FreeCAD is offline, so freecad_health can report a structured disconnected state. The bundled MCP configuration uses the root-relative freecad_mcp_codex.cmd launcher, which invokes python -m freecad_mcp_codex.server from the plugin root and remains relocatable when copied without the development virtual environment.

Live XML-RPC tests are opt-in through FREECAD_TEST_XMLRPC_PORT. Release CI should also set FREECAD_REQUIRE_LIVE_TESTS=true so a missing live bridge is a hard failure rather than a skip.

The positive release gate can launch an isolated bridge and run the live suite: pwsh -File tests/run_live_gate.ps1. Set FREECAD_TEST_FREECAD when FreeCAD is installed outside C:\Program Files\FreeCAD 1.1\bin\FreeCADCmd.exe. Ordinary developer runs continue to skip live tests when no bridge is available.

Security boundary

This is a trusted-local integration. Keep the MCP process and FreeCAD XML-RPC bridge bound to localhost. Only enable execute_freecad_python for code you authored and understand: it can read and write local files, mutate open documents, and use any capabilities available to the FreeCAD Python runtime. Do not expose the bridge or MCP stdio process to untrusted users or networks.

Available Tools

36 tools
boolean_commonA

Intersect two shapes in one validated transaction.

Inputs: object_a (required), object_b (required), doc_name, result_name. Returns: object

boolean_cutB

Subtract object_b from object_a in one validated transaction.

Inputs: object_a (required), object_b (required), doc_name, result_name. Returns: object

boolean_fuseC

Fuse two shapes in one validated transaction.

Inputs: object_a (required), object_b (required), doc_name, result_name. Returns: object

capture_viewB

Capture a PNG of the active FreeCAD 3D view.

Inputs: width, height, doc_name, view_angle. Returns: object

chamfer_edgesB

Chamfer selected edges, or all edges when edge_indices is omitted.

Inputs: distance (required), object_name (required), doc_name, result_name, +1 more. Returns: object

check_collisionB

Check whether two shapes overlap and report intersection volume.

Inputs: object_a (required), object_b (required), doc_name, tolerance. Returns: object

check_geometryC

Validate an object's BRep and return structured geometry diagnostics.

Inputs: object_name (required), doc_name. Returns: object

close_documentC

Close a FreeCAD document without saving it automatically.

Inputs: doc_name. Returns: object

create_boxC

Create and validate a Part box.

Inputs: name, width, height, length, +1 more. Returns: object

create_cylinderC

Create and validate a Part cylinder.

Inputs: name, angle, height, radius, +1 more. Returns: object

create_documentC

Create an empty FreeCAD document.

Inputs: name (required), label. Returns: object

create_fan_mountB

Create a square fan mounting plate with four clearance holes.

Inputs: name, size, doc_name, thickness, +2 more. Returns: object

create_heatset_insert_bossB

Create a hollow boss sized for a heat-set insert.

Inputs: height (required), outer_radius (required), insert_radius (required), name, +1 more. Returns: object

create_screw_bossC

Create a hollow cylindrical screw boss.

Inputs: height (required), hole_radius (required), outer_radius (required), name, +1 more. Returns: object

create_shellC

Create a rectangular open-top shell from [length,width,height].

Inputs: outer (required), name, wall, doc_name. Returns: object

create_vent_patternB

Create a vent plate with a regular array of through-slots.

Inputs: name, depth, width, height, +4 more. Returns: object

execute_freecad_pythonC

Execute FreeCAD Python only when FREECAD_ALLOW_EXECUTE_PYTHON=true.

Inputs: code (required), timeout_ms. Returns: object

export_stepC

Export selected or all shaped objects to STEP.

Inputs: file_path (required), doc_name, object_names. Returns: object

export_stlC

Export selected or all shaped objects to STL.

Inputs: file_path (required), doc_name, object_names, mesh_tolerance. Returns: object

fillet_edgesC

Fillet selected edges, or all edges when edge_indices is omitted.

Inputs: radius (required), object_name (required), doc_name, result_name, +1 more. Returns: object

freecad_healthA

Return structured bridge, FreeCAD version, and GUI health.

Inputs: no named parameters. Returns: object

get_bounding_boxB

Return an object's axis-aligned bounding box in document coordinates.

Inputs: object_name (required), doc_name. Returns: object

get_operation_statusA

Poll a timed-out FreeCAD operation until it is definitively complete.

Inputs: operation_id (required). Returns: object

import_stepC

Import a STEP file into the target document.

Inputs: file_path (required), name, doc_name. Returns: object

import_stlB

Import an STL mesh into the target document.

Inputs: file_path (required), name, doc_name. Returns: object

inspect_objectB

Inspect an object's properties, links, and shape summary.

Inputs: object_name (required), doc_name. Returns: object

inspect_shapeB

Return shape type, validity, topology counts, mass properties, and bounds.

Inputs: object_name (required), doc_name. Returns: object

list_documentsA

List open FreeCAD documents.

Inputs: no named parameters. Returns: result

list_objectsC

List object names, labels, types, and visibility.

Inputs: doc_name. Returns: result

measure_distanceA

Measure Euclidean distance between two XYZ points.

Inputs: point_a (required), point_b (required). Returns: object

open_documentA

Open an FCStd document and return its identity.

Inputs: path (required). Returns: object

save_documentC

Save a document to its existing path.

Inputs: doc_name. Returns: object

save_document_asC

Save a document to a new FCStd path.

Inputs: path (required), doc_name. Returns: object

set_placementB

Set an object's XYZ placement and optional yaw/pitch/roll Euler angles.

Inputs: object_name (required), doc_name, position, rotation. Returns: object

split_by_planeC

Split a shape by an axis-aligned plane and return two new objects.

Inputs: normal (required), object_name (required), offset, doc_name. Returns: object

split_for_print_bedC

Split a long object into print-bed-sized axis-aligned pieces.

Inputs: bed_width (required), bed_length (required), object_name (required), axis, +1 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 36 tools

    Disambiguation4/5

    Most tools target distinct resources and actions, so an agent can usually tell them apart. A few pairs overlap in scope — inspect_shape and get_bounding_box both return bounds, and split_by_plane and split_for_print_bed both split shapes — but the descriptions make the intended use reasonably clear.

    Naming Consistency4/5

    The set is predominantly lower_snake_case with an action+object pattern like list_documents, create_box, and export_step. It is not perfect because freecad_health is a noun-style outlier and the boolean_* tools use an adjective prefix instead of a clear verb.

    Tool Count2/5

    At 36 tools this is well past the 25+ threshold for an over-large set, and several niche print-preparation helpers such as screw boss, heatset boss, fan mount, vent pattern, and print-bed splitter broaden the surface beyond a tight CAD API. The count is not an extreme 50+ disaster, but it should be trimmed or consolidated for a more focused server.

    Completeness3/5

    The set covers document lifecycle, object inspection, primitive modeling, boolean operations, filleting/chamfering, splitting, and STEP/STL import/export, so the primary solid-modeling workflow is usable. Missing first-class operations like delete/rename/copy objects and any sketch/extrude/parametric capabilities leave notable gaps for general FreeCAD use, partially papered over by execute_freecad_python.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • 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
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI clients to create, edit, and export CAD models and drawings in a locally installed FreeCAD via MCP.
      3
      -
    • A
      license
      A
      quality
      B
      maintenance
      Gives MCP clients headless access to FreeCAD so they can inspect models for dimensions, validity and watertightness, convert between CAD and mesh formats like STEP, STL, 3MF, IGES and BREP, extract 2D DXF/SVG profiles for laser cutting, and run FreeCAD Python scripts for automation and CI.
      5
      MIT