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

Skip to content

# MCP Macro Tools

The MCP server provides tools for working with FreeCAD macros programmatically.

## Available Tools

### list_macros

List available macros in FreeCAD's macro directories.

    list_macros() -> list[dict]

Returns: List of macros with name, path, description, and whether it's a system macro.

### run_macro

Execute a macro by name with optional arguments.

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

Example prompt:

    "Run the ExportSTL macro"

### create_macro

Create a new macro programmatically.

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

Example prompt:

    "Create a macro called 'CreateBox' that makes a 10x10x10 box"

### read_macro

Read the source code of an existing macro.

    read_macro(macro_name: str) -> dict

Example prompt:

    "Show me the code for my custom macro"

### delete_macro

Delete a user macro (system macros are protected).

    delete_macro(macro_name: str) -> dict

### create_macro_from_template

Create a macro from predefined templates.

    create_macro_from_template(
        name: str,
        template: str = "basic",
        description: str = ""
    ) -> dict

Available templates:

Template | Description
--- | ---
`basic` | Minimal macro with imports
`part` | Part workbench operations
`sketch` | Sketcher operations
`gui` | GUI/dialog template
`selection` | Selection handling template

Example prompt:

    "Create a new macro from the 'sketch' template called 'DrawGear'"

## Macro Development with AI

The MCP server excels at helping develop FreeCAD macros. Example workflows:

### Debugging an Existing Macro

    "Read the macro 'MyMacro' and explain what it does"

    "Run the macro and show me any errors from the FreeCAD console"

### Creating a New Macro

    "Create a macro that:
    1. Gets all selected objects
    2. Calculates their combined bounding box
    3. Creates a box around them with 5mm clearance"

### Modifying a Macro

    "Read the 'ExportSTL' macro and modify it to also export STEP files"

## Best Practices for Macro Development

1. Use templates - Start from `create_macro_from_template` for proper imports
2. Test incrementally - Use `execute_python` for testing snippets before creating full macros
3. Check console output - Use `get_console_output` to debug issues
4. Document your macros - Add docstrings that explain parameters and usage
5. Handle errors gracefully - Wrap operations in try/except blocks

## Next Steps

- Tools Reference - Complete API for all MCP tools
- Workbench - Robust MCP Bridge Workbench details

2026-01-18
2026-01-06