FreeCAD Robust MCP Server Tools Reference¶

This document provides a comprehensive reference for all MCP tools available in the FreeCAD Robust MCP Server.

Overview¶

The FreeCAD Robust MCP Server exposes tools organized into the following categories:

Category	Description	Tool Count
Execution	Python execution and system info	5
Documents	Document management	7
Objects	Object creation and manipulation	22
PartDesign	Parametric solid modeling	20
Export	Import/export operations	7
View	View control and screenshots	18
Macros	Macro management	6
Total		85

Execution Tools¶

Tools for executing Python code and getting system information.

execute_python¶

Execute arbitrary Python code in FreeCAD's context.

execute_python(
    code: str,
    timeout_ms: int = 30000
) -> dict

Parameters:

code: Python code to execute. Use _result_ = value to return data.
timeout_ms: Maximum execution time in milliseconds.

Returns: Execution result with stdout, stderr, and any assigned _result_.

Example:

await execute_python('''
import Part
box = Part.makeBox(10, 20, 30)
_result_ = {"volume": box.Volume}
''')

get_freecad_version¶

Get FreeCAD version and build information.

get_freecad_version() -> dict

Returns: Version string, build date, Python version, GUI availability.

get_connection_status¶

Get the current bridge connection status.

get_connection_status() -> dict

Returns: Connection state, mode (xmlrpc/socket/embedded), latency.

get_console_output¶

Get recent FreeCAD console output.

get_console_output(lines: int = 100) -> list[str]

get_mcp_server_environment¶

Get environment information about the Robust MCP Server process. Useful for identifying the Robust MCP Server instance via the unique instance_id.

get_mcp_server_environment() -> dict

Returns: Dictionary containing:

instance_id: Unique UUID for this server instance (generated at startup)
hostname: Server hostname
os_name: Operating system name (e.g., "Linux", "Darwin", "Windows")
os_version: OS version/release
platform: Full platform string
python_version: Python version
freecad: FreeCAD connection information (connected, mode, version, gui_available, is_headless)
env_vars: Selected environment variables (FREECAD_MODE, ports, host)

Document Tools¶

Tools for managing FreeCAD documents.

list_documents¶

List all open documents.

list_documents() -> list[dict]

get_active_document¶

Get the currently active document.

get_active_document() -> dict | None

create_document¶

Create a new document.

create_document(
    name: str = "Unnamed",
    label: str | None = None
) -> dict

open_document¶

Open an existing FreeCAD file.

open_document(path: str) -> dict

save_document¶

Save a document.

save_document(
    doc_name: str | None = None,
    path: str | None = None
) -> dict

close_document¶

Close a document.

close_document(
    doc_name: str | None = None,
    save_changes: bool = False
) -> dict

recompute_document¶

Recompute all objects in a document.

recompute_document(doc_name: str | None = None) -> dict

Object Tools¶

Tools for creating and manipulating FreeCAD objects.

Primitive Creation¶

create_box¶

Create a parametric box.

create_box(
    length: float = 10.0,
    width: float = 10.0,
    height: float = 10.0,
    name: str | None = None,
    doc_name: str | None = None
) -> dict

create_cylinder¶

Create a parametric cylinder.

create_cylinder(
    radius: float = 5.0,
    height: float = 10.0,
    angle: float = 360.0,  # For partial cylinders
    name: str | None = None,
    doc_name: str | None = None
) -> dict

create_sphere¶

Create a parametric sphere.

create_sphere(
    radius: float = 5.0,
    name: str | None = None,
    doc_name: str | None = None
) -> dict

create_cone¶

Create a parametric cone.

create_cone(
    radius1: float = 5.0,   # Bottom radius
    radius2: float = 0.0,   # Top radius (0 = pointed)
    height: float = 10.0,
    angle: float = 360.0,
    name: str | None = None,
    doc_name: str | None = None
) -> dict

create_torus¶

Create a torus (donut shape).

create_torus(
    radius1: float = 10.0,  # Major radius
    radius2: float = 2.0,   # Minor radius
    angle1: float = -180.0,
    angle2: float = 180.0,
    angle3: float = 360.0,
    name: str | None = None,
    doc_name: str | None = None
) -> dict

create_wedge¶

Create a tapered wedge shape.

create_wedge(
    xmin: float = 0.0, ymin: float = 0.0, zmin: float = 0.0,
    x2min: float = 2.0, z2min: float = 2.0,
    xmax: float = 10.0, ymax: float = 10.0, zmax: float = 10.0,
    x2max: float = 8.0, z2max: float = 8.0,
    name: str | None = None,
    doc_name: str | None = None
) -> dict

create_helix¶

Create a helix curve (for threads, springs).

create_helix(
    pitch: float = 5.0,
    height: float = 20.0,
    radius: float = 5.0,
    angle: float = 0.0,
    left_handed: bool = False,
    name: str | None = None,
    doc_name: str | None = None
) -> dict

Object Management¶

list_objects¶

List all objects in a document.

list_objects(doc_name: str | None = None) -> list[dict]

inspect_object¶

Get detailed information about an object.

inspect_object(
    object_name: str,
    doc_name: str | None = None,
    include_properties: bool = True,
    include_shape: bool = True
) -> dict

create_object¶

Create a generic FreeCAD object by type ID.

create_object(
    type_id: str,  # e.g., "Part::Box", "Sketcher::SketchObject"
    name: str | None = None,
    properties: dict[str, Any] | None = None,
    doc_name: str | None = None
) -> dict

edit_object¶

Modify object properties.

edit_object(
    object_name: str,
    properties: dict[str, Any],
    doc_name: str | None = None
) -> dict

delete_object¶

Delete an object.

delete_object(
    object_name: str,
    doc_name: str | None = None
) -> dict

Boolean Operations¶

boolean_operation¶

Perform boolean operations (union, subtract, intersect).

boolean_operation(
    operation: str,      # "fuse", "cut", or "common"
    object1_name: str,
    object2_name: str,
    result_name: str | None = None,
    doc_name: str | None = None
) -> dict

Operations:

fuse - Union/combine shapes
cut - Subtract object2 from object1
common - Intersection of shapes

Transformations¶

set_placement¶

Set object position and rotation.

set_placement(
    object_name: str,
    position: list[float] | None = None,  # [x, y, z]
    rotation: list[float] | None = None,  # [yaw, pitch, roll] in degrees
    doc_name: str | None = None
) -> dict

rotate_object¶

Rotate object around an axis.

rotate_object(
    object_name: str,
    axis: list[float],      # [x, y, z] rotation axis
    angle: float,           # Degrees
    center: list[float] | None = None,
    doc_name: str | None = None
) -> dict

scale_object¶

Scale an object (creates new copy).

scale_object(
    object_name: str,
    scale: float | list[float],  # Uniform or [sx, sy, sz]
    result_name: str | None = None,
    doc_name: str | None = None
) -> dict

copy_object¶

Create a copy of an object.

copy_object(
    object_name: str,
    new_name: str | None = None,
    offset: list[float] | None = None,  # [x, y, z]
    doc_name: str | None = None
) -> dict

mirror_object¶

Mirror object across a plane.

mirror_object(
    object_name: str,
    plane: str = "XY",  # "XY", "XZ", or "YZ"
    result_name: str | None = None,
    doc_name: str | None = None
) -> dict

Selection (GUI Mode)¶

get_selection¶

Get currently selected objects.

get_selection(doc_name: str | None = None) -> list[dict]

set_selection¶

Select objects programmatically.

set_selection(
    object_names: list[str],
    clear_existing: bool = True,
    doc_name: str | None = None
) -> dict

clear_selection¶

Clear the current selection.

clear_selection() -> dict

PartDesign Tools¶

Tools for parametric solid modeling using the PartDesign workbench.

Bodies and Sketches¶

create_partdesign_body¶

Create a PartDesign Body container.

create_partdesign_body(
    name: str | None = None,
    doc_name: str | None = None
) -> dict

create_sketch¶

Create a sketch attached to a plane or body.

create_sketch(
    body_name: str | None = None,
    plane: str = "XY_Plane",  # "XY_Plane", "XZ_Plane", "YZ_Plane", or "FaceN"
    name: str | None = None,
    doc_name: str | None = None
) -> dict

Sketch Geometry¶

add_sketch_rectangle¶

Add a rectangle to a sketch.

add_sketch_rectangle(
    sketch_name: str,
    x: float, y: float,       # Bottom-left corner
    width: float, height: float,
    doc_name: str | None = None
) -> dict

add_sketch_circle¶

Add a circle to a sketch.

add_sketch_circle(
    sketch_name: str,
    center_x: float, center_y: float,
    radius: float,
    doc_name: str | None = None
) -> dict

add_sketch_line¶

Add a line to a sketch.

add_sketch_line(
    sketch_name: str,
    x1: float, y1: float,  # Start point
    x2: float, y2: float,  # End point
    construction: bool = False,
    doc_name: str | None = None
) -> dict

add_sketch_arc¶

Add an arc to a sketch.

add_sketch_arc(
    sketch_name: str,
    center_x: float, center_y: float,
    radius: float,
    start_angle: float,  # Degrees
    end_angle: float,    # Degrees
    doc_name: str | None = None
) -> dict

add_sketch_point¶

Add a point to a sketch (useful for hole centers).

add_sketch_point(
    sketch_name: str,
    x: float, y: float,
    doc_name: str | None = None
) -> dict

Additive Features¶

pad_sketch¶

Extrude a sketch to create material.

pad_sketch(
    sketch_name: str,
    length: float,
    symmetric: bool = False,
    reversed: bool = False,
    name: str | None = None,
    doc_name: str | None = None
) -> dict

revolution_sketch¶

Revolve a sketch around an axis.

revolution_sketch(
    sketch_name: str,
    angle: float = 360.0,
    axis: str = "Base_X",  # "Base_X/Y/Z" or "Sketch_V/H"
    symmetric: bool = False,
    reversed: bool = False,
    name: str | None = None,
    doc_name: str | None = None
) -> dict

loft_sketches¶

Loft through multiple sketches.

loft_sketches(
    sketch_names: list[str],
    ruled: bool = False,
    closed: bool = False,
    name: str | None = None,
    doc_name: str | None = None
) -> dict

sweep_sketch¶

Sweep a profile along a path.

sweep_sketch(
    profile_sketch: str,
    spine_sketch: str,
    transition: str = "Transformed",  # "Transformed", "Right", "Round"
    name: str | None = None,
    doc_name: str | None = None
) -> dict

Subtractive Features¶

pocket_sketch¶

Cut material by extruding a sketch.

pocket_sketch(
    sketch_name: str,
    length: float,
    type: str = "Length",  # "Length", "ThroughAll", "UpToFirst", "UpToFace"
    name: str | None = None,
    doc_name: str | None = None
) -> dict

groove_sketch¶

Cut material by revolving a sketch.

groove_sketch(
    sketch_name: str,
    angle: float = 360.0,
    axis: str = "Base_X",
    symmetric: bool = False,
    reversed: bool = False,
    name: str | None = None,
    doc_name: str | None = None
) -> dict

create_hole¶

Create parametric holes with optional threading.

create_hole(
    sketch_name: str,        # Sketch with center point(s)
    diameter: float = 6.0,
    depth: float = 10.0,
    hole_type: str = "Dimension",  # "Dimension", "ThroughAll", "UpToFirst"
    threaded: bool = False,
    thread_type: str = "ISO",  # "ISO", "UNC", "UNF"
    thread_size: str = "M6",
    name: str | None = None,
    doc_name: str | None = None
) -> dict

Edge Operations¶

fillet_edges¶

Add rounded edges.

fillet_edges(
    object_name: str,
    radius: float,
    edges: list[str] | None = None,  # ["Edge1", "Edge2"] or None for all
    name: str | None = None,
    doc_name: str | None = None
) -> dict

chamfer_edges¶

Add beveled edges.

chamfer_edges(
    object_name: str,
    size: float,
    edges: list[str] | None = None,
    name: str | None = None,
    doc_name: str | None = None
) -> dict

Patterns¶

linear_pattern¶

Repeat a feature in a linear direction.

linear_pattern(
    feature_name: str,
    direction: str = "X",  # "X", "Y", "Z"
    length: float = 50.0,
    occurrences: int = 3,
    name: str | None = None,
    doc_name: str | None = None
) -> dict

polar_pattern¶

Repeat a feature around an axis.

polar_pattern(
    feature_name: str,
    axis: str = "Z",  # "X", "Y", "Z"
    angle: float = 360.0,
    occurrences: int = 6,
    name: str | None = None,
    doc_name: str | None = None
) -> dict

mirrored_feature¶

Mirror a feature across a plane.

mirrored_feature(
    feature_name: str,
    plane: str = "XY",  # "XY", "XZ", "YZ"
    name: str | None = None,
    doc_name: str | None = None
) -> dict

Export Tools¶

Tools for importing and exporting CAD files.

export_step¶

Export objects to STEP format.

export_step(
    file_path: str,
    object_names: list[str] | None = None,  # None = all visible
    doc_name: str | None = None
) -> dict

export_stl¶

Export objects to STL format (for 3D printing).

export_stl(
    file_path: str,
    object_names: list[str] | None = None,
    doc_name: str | None = None,
    mesh_tolerance: float = 0.1
) -> dict

export_3mf¶

Export objects to 3MF format (modern 3D printing format).

3MF (3D Manufacturing Format) supports richer data than STL, including colors, materials, and print settings. It is increasingly preferred over STL for 3D printing.

export_3mf(
    file_path: str,
    object_names: list[str] | None = None,
    doc_name: str | None = None,
    mesh_tolerance: float = 0.1
) -> dict

export_obj¶

Export objects to OBJ format.

export_obj(
    file_path: str,
    object_names: list[str] | None = None,
    doc_name: str | None = None
) -> dict

export_iges¶

Export objects to IGES format.

export_iges(
    file_path: str,
    object_names: list[str] | None = None,
    doc_name: str | None = None
) -> dict

import_step¶

Import a STEP file.

import_step(
    file_path: str,
    doc_name: str | None = None
) -> dict

import_stl¶

Import an STL file.

import_stl(
    file_path: str,
    doc_name: str | None = None
) -> dict

View Tools¶

Tools for controlling the 3D view and capturing screenshots.

Screenshots¶

get_screenshot¶

Capture a screenshot of the 3D view.

Requires GUI mode.

get_screenshot(
    view_angle: str = "Isometric",
    width: int = 800,
    height: int = 600,
    doc_name: str | None = None
) -> dict  # Returns base64-encoded PNG

View angles: Isometric, Front, Back, Top, Bottom, Left, Right, FitAll

View Control¶

set_view_angle¶

Set the 3D view angle.

set_view_angle(
    view_angle: str,  # Same options as get_screenshot
    doc_name: str | None = None
) -> dict

fit_all¶

Fit all objects in the view.

fit_all(doc_name: str | None = None) -> dict

zoom_in / zoom_out¶

Zoom the view.

Requires GUI mode.

zoom_in(factor: float = 1.5, doc_name: str | None = None) -> dict
zoom_out(factor: float = 1.5, doc_name: str | None = None) -> dict

set_camera_position¶

Set custom camera position.

Requires GUI mode.

set_camera_position(
    position: list[float],     # [x, y, z]
    look_at: list[float] | None = None,  # Default: origin
    doc_name: str | None = None
) -> dict

Object Appearance¶

set_object_visibility¶

Show or hide an object.

Requires GUI mode.

set_object_visibility(
    object_name: str,
    visible: bool,
    doc_name: str | None = None
) -> dict

set_display_mode¶

Set object display mode.

Requires GUI mode.

set_display_mode(
    object_name: str,
    mode: str,  # "Flat Lines", "Shaded", "Wireframe", "Points"
    doc_name: str | None = None
) -> dict

set_object_color¶

Set object color.

Requires GUI mode.

set_object_color(
    object_name: str,
    color: list[float],  # [r, g, b] where values are 0.0-1.0
    doc_name: str | None = None
) -> dict

Workbenches¶

list_workbenches¶

List available workbenches.

list_workbenches() -> list[dict]

activate_workbench¶

Activate a workbench.

activate_workbench(workbench_name: str) -> dict

Common workbenches:

PartWorkbench - Part modeling
PartDesignWorkbench - Parametric design
SketcherWorkbench - 2D sketching
DraftWorkbench - 2D drafting
MeshWorkbench - Mesh operations

Undo/Redo¶

undo / redo¶

Undo or redo operations.

undo(doc_name: str | None = None) -> dict
redo(doc_name: str | None = None) -> dict

get_undo_redo_status¶

Get undo/redo availability.

get_undo_redo_status(doc_name: str | None = None) -> dict

Parts Library¶

list_parts_library¶

List available library parts.

list_parts_library() -> list[dict]

insert_part_from_library¶

Insert a part from the library.

insert_part_from_library(
    part_path: str,
    name: str | None = None,
    position: list[float] | None = None,
    doc_name: str | None = None
) -> dict

Utility¶

get_console_log¶

Get FreeCAD console output.

get_console_log(lines: int = 50) -> dict

recompute¶

Force recompute of all objects.

recompute(doc_name: str | None = None) -> dict

Macro Tools¶

Tools for managing FreeCAD macros.

list_macros¶

List available macros.

list_macros() -> list[dict]

run_macro¶

Execute a macro by name.

run_macro(
    macro_name: str,
    args: dict[str, Any] | None = None
) -> dict

create_macro¶

Create a new macro.

create_macro(
    name: str,
    code: str,
    description: str = ""
) -> dict

read_macro¶

Read macro contents.

read_macro(macro_name: str) -> dict

delete_macro¶

Delete a user macro.

delete_macro(macro_name: str) -> dict

create_macro_from_template¶

Create macro from a predefined template.

create_macro_from_template(
    name: str,
    template: str = "basic",  # "basic", "part", "sketch", "gui", "selection"
    description: str = ""
) -> dict

GUI vs Headless Mode¶

Some tools require FreeCAD to be running in GUI mode. When running in headless mode, these tools will return an error instead of crashing.

GUI-only tools:

get_screenshot
set_object_visibility
set_display_mode
set_object_color
zoom_in / zoom_out
set_camera_position
get_selection / set_selection / clear_selection

To check mode programmatically:

result = await execute_python("_result_ = FreeCAD.GuiUp")
is_gui_mode = result["result"]

Error Handling¶

All tools return dictionaries with consistent error handling:

Success:

{
    "success": True,
    "name": "Box",
    "volume": 6000.0,
    # ... other fields
}

Failure:

{
    "success": False,
    "error": "Object not found: MissingBox"
}

For tools that raise exceptions, wrap calls in try/except or check the returned error field.