FreeCAD MCP for Codex
This server exposes a local FreeCAD MCP bridge for inspecting, creating, modifying, validating, and exporting 3D CAD models via XML-RPC.
Check FreeCAD bridge, version, GUI health, and poll long-running operations.
Manage documents: list, open, create, save, save-as, and close.
Inspect objects and geometry: list objects, inspect object/shape, bounding box, distance, collision, and BRep validation.
Capture PNG screenshots of the active 3D view.
Create primitives and practical features: box, cylinder, shell, screw boss, heat-set insert boss, fan mount, and vent pattern.
Modify models: set placement, boolean cut/fuse/common, fillet/chamfer edges, split by plane, and split for print bed.
Import/export STEP and STL files.
Execute arbitrary FreeCAD Python only when
FREECAD_ALLOW_EXECUTE_PYTHON=true, for trusted local code.
Provides tools for interacting with FreeCAD, enabling AI agents to inspect and manipulate CAD documents, execute FreeCAD Python code when enabled, and query bridge health through a local XML-RPC connection.
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 for Codex Create a new FreeCAD document and add a cylinder"
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 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.
Install the addon folder
freecad-addon/RobustMCPBridgeinto FreeCAD's userModdirectory. For FreeCAD 1.1 on Windows, use%APPDATA%\FreeCAD\v1-1\Mod\RobustMCPBridge. Create theModdirectory if it does not exist, then copy the wholeRobustMCPBridgefolder there.Restart FreeCAD so it loads the workbench.
In the workbench selector, choose Robust MCP Bridge.
Click Start MCP Bridge in its toolbar, or run Robust MCP Bridge → Start MCP Bridge from the menu.
The default Codex connection uses XML-RPC at
localhost:9875. The workbench status command or status-bar indicator should show the bridge as running.In Codex, call
freecad_health; it should reportconnected: 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 9875The 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 toolsboolean_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
Scored across 36 tools
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.
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.
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.
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
Related MCP Connectors
Global CAD/BIM, industrial engineering (FEM, CFD) and property tools via one MCP endpoint.
Headless CAD engine & MCP server for 2D/3D drafting, solids, DXF/SVG export, and automation.
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables to control FreeCAD from Claude Desktop through MCP, allowing CAD operations like creating and editing objects, taking screenshots, and executing Python code.111MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with FreeCAD for 3D modeling, macros, and debugging via MCP.MIT
- FlicenseNot gradedqualityCmaintenanceEnables AI clients to create, edit, and export CAD models and drawings in a locally installed FreeCAD via MCP.3-
- AlicenseAqualityBmaintenanceGives 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.5MIT