The FreeCAD Robust MCP Server provides 150+ tools for CAD operations. This page provides a quick reference organized by category.
Transaction Support
All MCP operations are wrapped in FreeCAD transactions for undo support. After any operation, you can use undo to revert changes. This makes it safe for AI agents to experiment and recover from mistakes.
For detailed documentation including parameters and examples, see MCP Tools Reference.
| Tool | Description |
execute_python | Execute arbitrary Python in FreeCAD |
get_freecad_version | Get FreeCAD version and build info |
get_connection_status | Check MCP bridge connection |
get_console_output | Get recent console output |
get_mcp_server_environment | Get Robust MCP Server environment info |
| Tool | Description |
list_documents | List all open documents |
get_active_document | Get currently active document |
create_document | Create a new document |
open_document | Open an existing .FCStd file |
save_document | Save a document |
close_document | Close a document |
recompute_document | Recompute all features |
| Tool | Description |
create_box | Create a parametric box |
create_cylinder | Create a parametric cylinder |
create_sphere | Create a parametric sphere |
create_cone | Create a parametric cone |
create_torus | Create a torus (donut) |
create_wedge | Create a tapered wedge |
create_helix | Create a helix curve |
create_object | Create any object by type ID |
The Part workbench provides direct shape creation and manipulation tools using OpenCASCADE geometry.
Shape Creation
| Tool | Description |
part_make_line | Create a line between two points |
part_make_wire | Create a wire from connected edges |
part_make_face | Create a face from a closed wire |
part_make_shell | Create a shell from faces |
part_make_solid | Create a solid from a closed shell |
part_make_compound | Create a compound from multiple shapes |
part_make_polygon | Create a polygon wire from points |
part_make_circle | Create a circle edge or wire |
part_make_ellipse | Create an ellipse edge |
part_make_b_spline | Create a B-spline curve from points |
Shape Operations
| Tool | Description |
part_fuse | Boolean union (combine shapes) |
part_cut | Boolean subtraction (cut one from another) |
part_common | Boolean intersection (common volume) |
part_fillet | Add fillets to shape edges |
part_chamfer | Add chamfers to shape edges |
part_extrude | Extrude a shape along a vector |
part_revolve | Revolve a shape around an axis |
part_loft | Create a loft through multiple profiles |
part_sweep | Sweep a profile along a path |
part_offset | Create an offset shell of a shape |
part_slice | Slice a shape with a plane |
part_section | Create intersection curve of two shapes |
Shape Queries
| Tool | Description |
part_check_shape | Validate shape geometry |
part_get_faces | Get all faces of a shape |
part_get_edges | Get all edges of a shape |
part_get_vertices | Get all vertices of a shape |
part_measure_distance | Measure distance between shapes |
part_measure_angle | Measure angle between faces/edges |
part_get_center_of_mass | Calculate center of mass |
part_get_bounding_box | Get axis-aligned bounding box |
| Tool | Description |
list_objects | List objects in a document |
inspect_object | Get detailed object information |
edit_object | Modify object properties |
delete_object | Delete an object |
boolean_operation | Union, cut, or intersect objects |
set_placement | Set position and rotation |
rotate_object | Rotate around an axis |
scale_object | Scale uniformly or non-uniformly |
copy_object | Create a copy |
mirror_object | Mirror across a plane |
get_selection | Get selected objects (GUI) |
set_selection | Select objects (GUI) |
clear_selection | Clear selection (GUI) |
Bodies and Sketches
| Tool | Description |
create_partdesign_body | Create a PartDesign body |
create_sketch | Create a sketch on a plane/face |
Datum Features
| Tool | Description |
partdesign_create_datum_point | Create a datum point for construction |
partdesign_create_datum_line | Create a datum line/axis |
partdesign_create_datum_plane | Create a datum plane for sketches |
Basic Sketch Geometry
| Tool | Description |
add_sketch_rectangle | Add rectangle to sketch |
add_sketch_circle | Add circle to sketch |
add_sketch_line | Add line to sketch |
add_sketch_arc | Add arc to sketch |
add_sketch_point | Add point to sketch |
Additive Features
| Tool | Description |
pad_sketch | Extrude sketch (additive) |
revolution_sketch | Revolve sketch around axis |
loft_sketches | Loft through multiple sketches |
sweep_sketch | Sweep profile along path |
partdesign_create_additive_pipe | Pipe/sweep with auxiliary path |
partdesign_create_additive_loft | Loft with more options |
Subtractive Features
| Tool | Description |
pocket_sketch | Cut by extruding sketch |
groove_sketch | Cut by revolving sketch |
create_hole | Create parametric holes |
partdesign_create_subtractive_pipe | Subtractive pipe/sweep |
partdesign_create_subtractive_loft | Subtractive loft |
Symmetric Operations
pad_sketch, pocket_sketch, revolution_sketch, and groove_sketch accept symmetric=True to distribute the operation on both sides of the sketch plane. The tools use FreeCAD's SideType property when available (1.1+) and fall back to Midplane/Symmetric on older releases. When pocket_sketch uses the Midplane fallback, symmetric pockets only support Length and ThroughAll. Other termination modes are rejected because FreeCAD would otherwise make a one-sided cut.
Dress-up Features
| Tool | Description |
fillet_edges | Add rounded edges |
chamfer_edges | Add beveled edges |
partdesign_create_thickness | Shell/hollow a solid |
partdesign_create_draft | Add draft angle to faces |
Patterns
| Tool | Description |
linear_pattern | Repeat feature linearly |
polar_pattern | Repeat feature circularly |
mirrored_feature | Mirror feature across plane |
Extended sketch geometry and manipulation tools beyond the basic shapes.
Additional Geometry
| Tool | Description |
sketcher_add_ellipse | Add ellipse to sketch |
sketcher_add_b_spline | Add B-spline curve from control points |
sketcher_add_polygon | Add regular polygon |
sketcher_add_slot | Add slot (rounded rectangle) |
Edge Operations
| Tool | Description |
sketcher_add_fillet | Fillet corner between two lines |
sketcher_add_chamfer | Chamfer corner between two lines |
sketcher_trim_curve | Trim curve at intersection |
sketcher_extend_curve | Extend curve to boundary |
sketcher_split_curve | Split curve at a point |
sketcher_offset_curve | Create offset copy of curve |
| Tool | Description |
sketcher_mirror | Mirror geometry across axis |
sketcher_array_linear | Create linear array of geometry |
sketcher_array_polar | Create polar array of geometry |
Sketcher Constraints
Constraints define relationships between sketch geometry elements.
Geometric Constraints
| Tool | Description |
sketcher_add_constraint_horizontal | Make line horizontal |
sketcher_add_constraint_vertical | Make line vertical |
sketcher_add_constraint_coincident | Make two points coincide |
sketcher_add_constraint_point_on_object | Place point on line/curve |
sketcher_add_constraint_parallel | Make lines parallel |
sketcher_add_constraint_perpendicular | Make lines perpendicular |
sketcher_add_constraint_tangent | Make curves tangent |
sketcher_add_constraint_equal | Make lengths/radii equal |
sketcher_add_constraint_symmetric | Make points symmetric about a line |
Dimensional Constraints
| Tool | Description |
sketcher_add_constraint_distance | Set distance between elements |
sketcher_add_constraint_radius | Set circle/arc radius |
sketcher_add_constraint_diameter | Set circle/arc diameter |
sketcher_add_constraint_angle | Set angle between lines |
Fix/Lock Constraints
| Tool | Description |
sketcher_add_constraint_lock | Lock point to specific coordinates |
sketcher_add_constraint_block | Block element from moving |
sketcher_add_constraint_fix | Fix point position |
Constraint Management
| Tool | Description |
sketcher_delete_constraint | Delete a constraint by index |
The Spreadsheet workbench enables parametric design by storing values in cells that can drive model dimensions through expressions.
| Tool | Description |
spreadsheet_create | Create a new Spreadsheet object |
spreadsheet_set_cell | Set cell value (number, string, or formula) |
spreadsheet_get_cell | Get cell value and computed result |
spreadsheet_set_alias | Set alias for parametric references |
spreadsheet_get_aliases | Get all aliases in a spreadsheet |
spreadsheet_clear_cell | Clear a cell and its alias |
spreadsheet_bind_property | Bind object property to spreadsheet cell |
spreadsheet_get_cell_range | Get values from a range of cells |
spreadsheet_import_csv | Import CSV data into spreadsheet |
spreadsheet_export_csv | Export spreadsheet to CSV file |
Parametric Design Workflow
- Create a spreadsheet with
spreadsheet_create - Set parameter values with
spreadsheet_set_cell - Define aliases with
spreadsheet_set_alias (e.g., "Length", "Width") - Bind to object properties with
spreadsheet_bind_property - Now changing the spreadsheet cell updates the model automatically!
The Draft workbench ShapeString tools create 3D text geometry that can be used for embossing, engraving, or standalone 3D text objects.
| Tool | Description |
draft_shapestring | Create 3D text geometry from font |
draft_list_fonts | List available system fonts |
draft_shapestring_to_sketch | Convert ShapeString to Sketch |
draft_shapestring_to_face | Convert ShapeString to Face |
draft_text_on_surface | Emboss or engrave text on a surface |
draft_extrude_shapestring | Extrude ShapeString to 3D solid |
draft_shapestring returns the internal object name for use with other tools; label is the displayed name. draft_shapestring_to_sketch accepts that internal name or an unambiguous label, preserves closed text contours, and reports conversion failures instead of returning an incomplete sketch. The converted sketch is a snapshot: editing the original ShapeString does not update it. Check placement and view direction before cutting or embossing. Use recompute_document and inspect any reported invalid objects before saving or exporting.
Text Embossing Workflow
# Create a box
await create_box(length=100, width=50, height=20)
# Engrave text on top face
await draft_text_on_surface(
text="SAMPLE",
target_face="Face6", # Top face
target_object="Box",
depth=1.5,
size=8,
operation="engrave" # or "emboss" for raised text
)
Tools for checking object and document health, with automatic recovery.
| Tool | Description |
validate_object | Check shape validity, error states, recompute |
validate_document | Check all objects in document, return summary |
undo_if_invalid | Validate and auto-undo if invalid objects exist |
safe_execute | Execute code with validation and auto-rollback |
Recovery Pattern
Use undo_if_invalid after complex operations to automatically recover from failures.
Tools marked with GUI only work when FreeCAD is running in GUI mode.
| Tool | Mode | Description |
get_screenshot | GUI | Capture 3D view screenshot |
set_view_angle | Both | Set camera angle |
fit_all | Both | Fit all objects in view |
zoom_in | GUI | Zoom in |
zoom_out | GUI | Zoom out |
set_camera_position | GUI | Set exact camera position |
set_object_visibility | GUI | Show/hide objects |
set_display_mode | GUI | Set display mode (wireframe, etc.) |
set_object_color | GUI | Change object color |
list_workbenches | Both | List available workbenches |
activate_workbench | Both | Switch workbench |
get_screenshot accepts view_angle, width, height, and doc_name. It returns PNG data encoded as base64 in data; it does not accept a file path.
| Tool | Description |
export_step | Export to STEP format |
export_stl | Export to STL (3D printing) |
export_3mf | Export to 3MF (modern 3D printing) |
export_obj | Export to OBJ format |
export_iges | Export to IGES format |
import_step | Import STEP files |
import_stl | Import STL files |
Build CAM jobs and G-code without dialogs. Available operations and dressups depend on the FreeCAD version and GUI availability; use cam_get_capabilities and cam_describe_type to discover the options. CAM requires a compatible Robust MCP Bridge workbench; update it and restart FreeCAD if requested.
| Tool | Description |
cam_get_capabilities | List CAM operation/dressup types, post processors, templates, known FreeCAD issues |
cam_list_tool_library | List tool libraries, tool bits and tool shapes |
cam_analyze_model | List model faces and drillable holes to choose Base features |
cam_create_job | Create a CAM job (no dialog), optional template, model offset, stock |
cam_set_stock | Replace job stock (from_base margins, box, cylinder) and/or set its material |
cam_add_tool_controller | Add tool bit; speeds and feeds from its preset for the stock material, or given |
cam_feeds_speeds | Compare tool controllers with FreeCAD's feeds & speeds presets; optionally apply |
cam_remove_tool_controller | Remove an unused tool controller |
cam_add_operation | Add any CAM operation (Profile, Pocket, Adaptive, Drilling, Helix, ...) |
cam_add_dressup | Add a dressup (Tags, Boundary, Dogbone, LeadInOut, RampEntry, ...) |
cam_describe_type | List every option of an operation/dressup type with defaults |
cam_get_properties | Read all properties of a CAM object with metadata |
cam_set_properties | Set validated properties/expressions on a CAM object |
cam_set_operation_order | Reorder job operations (G-code order) |
cam_inspect_job | Describe job: stock, tools, operations with path checks |
cam_inspect_path | Toolpath summary and warnings of one operation |
cam_post_process | Post-process to G-code without dialogs, write file |
cam_export_job_template | Save job settings as FreeCAD job_*.json template |
cam_check_job | FreeCAD job check (Sanity): findings, summary, optional HTML report |
cam_simulate | Voxel material removal simulation; gouge and material-left check against the part |
cam_place_model | Turn/move the part in a job (flip for a second setup), stock follows |
cam_import_tool_library | Import a .fctl or Camotics .json tool library with its tool bits |
cam_export_tool_library | Export a tool library as .fctl, Camotics .json or LinuxCNC .tbl |
Always independently review generated G-code and verify it in a suitable machine simulator before running it. The included voxel simulation is top-down and three-axis only; it does not model feeds, tool holders, or machine collisions. Explicit output files are protected from overwrite unless overwrite=True. On POSIX systems, new output files respect the process umask and are never world-writable; replacing an existing file preserves its permission bits. Replacement creates a new file and does not guarantee preservation of its previous owner, group, or access-control list; review those settings when they matter to your workflow. For secure staging, the POSIX output directory and its ancestors must be owned by the current user or root and must not be writable by other users unless the sticky bit is set. If needed, export to a private directory and copy the verified program to the destination. Split output is prepared before publication. Publication is not atomic as a group; if it fails, the error lists files already published. Inspect the output directory before using any of the files. If a filesystem cannot publish a new file atomically without replacing an existing one, select another output location and copy the verified program.
cam_post_process(use_job_output=True) writes the files where FreeCAD's Post Process command would, named by the job's output pattern (Job.PostProcessorOutputFile, e.g. %D/%S-%t-%d.nc). On FreeCAD 26.3+ a job with a machine (Job.Machine, a .fcm file in CamAssets/Machines) gets its post processor and options from the machine.
Speeds and feeds (FreeCAD 26.3+): a tool bit can carry presets (cutting speed and chipload per stock material and operation type, the tool editor's "Presets" tab). cam_add_tool_controller applies the preset matching the job's stock material (cam_set_stock(material=...), choices in cam_get_capabilities stock_materials), as the tool controller's "Feeds and Speeds Wizard" does. feeds_speeds="resolver" also allows FreeCAD's fallback to the material's generic surface speed; "none" turns it off.
cam_add_operation also creates Comment, Stop, Copy, Array and SimpleCopy (source_operations=[...]); cam_add_dressup also Boundary2, Mirror and PlungeMilling (FreeCAD 26.3+, GUI only). LeadInOut, RampEntry, Dragknife, AxisMap and ZCorrect also require the GUI. cam_simulate uses FreeCAD's voxel simulator (3-axis, from above).
FreeCAD versions: the CAM tools are tested with FreeCAD 1.0, 1.1, 26.3 and the weekly builds. FreeCAD 1.0 keeps tool bits as files, so it takes tool={"shape": ...} or {"bit_file": ...}; library bits and tool library import/export need FreeCAD 1.1+. Known FreeCAD bugs are reported in known_freecad_issues instead of being worked around: without the GUI, FreeCAD before 26.3 cannot add an operation to a job with several tool controllers (tc-console-mode), and FreeCAD 1.0 cannot create hole operations such as Drilling from a script (hole-op-create).
| Tool | Description |
list_macros | List available macros |
run_macro | Execute a macro |
create_macro | Create a new macro |
read_macro | Read macro source code |
delete_macro | Delete a user macro |
create_macro_from_template | Create from predefined template |
| Tool | Description |
undo | Undo last operation |
redo | Redo undone operation |
get_undo_redo_status | Get undo/redo availability |
recompute | Force recompute all objects |
get_console_log | Get console log with levels |
list_parts_library | List parts library |
insert_part_from_library | Insert part from library |
GUI vs Headless Mode
When running in headless mode, GUI-only tools return structured errors instead of crashing:
{
"success": false,
"error": "GUI not available - screenshots cannot be captured in headless mode"
}
To check the current mode programmatically:
result = await execute_python("_result_ = FreeCAD.GuiUp")
is_gui_mode = result["result"]
Next Steps