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