# Tools Reference - FreeCAD Robust MCP Suite
FreeCAD Robust MCP Suite - MCP Server, Bridge Workbench, and Macros for AI assistant integration

Skip to content

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

2026-01-10
2026-01-04