freecad-robust-mcp-fc111/docs/guide/macros.md

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