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

FreeCAD Macros

This project includes standalone FreeCAD macros that work independently of the MCP server, plus MCP tools for creating and managing macros programmatically.

---

Included Macros

CutObjectForMagnets

Cut an object along a plane and add aligned magnet holes with surface collision detection. Perfect for creating 3D printed parts that snap together with embedded magnets.

Features:

• Interactive plane selection via GUI
• Automatic magnet hole placement with configurable grid
• Surface collision detection to avoid invalid hole positions
• Configurable magnet dimensions and tolerances

Usage:

1. Select an object in FreeCAD
2. Run the macro
3. Define the cutting plane interactively
4. Configure magnet parameters
5. The macro creates two halves with aligned magnet holes

See CutObjectForMagnets documentation for detailed usage.

MultiExport

Export selected bodies to multiple file formats simultaneously with configurable mesh options.

Supported Formats:

• STL (ASCII and Binary)
• STEP
• 3MF
• OBJ
• IGES
• BREP
• PLY
• AMF

Usage:

1. Select one or more bodies/parts
2. Run the macro
3. Select output formats and configure mesh options
4. Choose output directory
5. All exports are created with consistent naming

See MultiExport documentation for detailed usage.

---

Installing Macros

Via FreeCAD Addon Manager

When you install the "FreeCAD MCP and More" addon, the macros are installed automatically.

Manual Installation

1. Download macros from GitHub Releases
2. Copy .FCMacro files to your macro directory:
   • Linux: ~/.local/share/FreeCAD/Macro/
   • macOS: ~/Library/Application Support/FreeCAD/Macro/
   • Windows: %APPDATA%\FreeCAD\Macro\

---

MCP Macro Tools

The MCP server provides tools for working with macros programmatically:

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 MultiExport 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 the MultiExport 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 - MCP Bridge Workbench details