FreeCAD MCP Server

Model Context Protocol server for FreeCAD - Connect Claude AI to FreeCAD for AI-powered 3D modeling

A Model Context Protocol (MCP) server for controlling FreeCAD, enabling AI assistants like Claude to create and manipulate 3D models.

Features

• Create 3D objects (boxes, cylinders, spheres)
• Export models to STEP, STL, and OBJ formats
• Full integration with Claude Desktop
• Type-safe Python implementation
• Comprehensive error handling and logging

Requirements

• Python 3.10 or higher
• FreeCAD installed at /Applications/FreeCAD.app (macOS)
• Claude Desktop (for MCP integration)

Installation

1. Install FreeCAD

Download and install FreeCAD from freecad.org.

On macOS, ensure it's installed at the default location:

/Applications/FreeCAD.app

2. Install the MCP Server

Clone or download this repository, then install:

cd freecad-mcp
pip install -e .

This installs the package in editable mode with all dependencies.

3. Configure Claude Desktop

Edit your Claude Desktop MCP configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the following configuration:

{
  "mcpServers": {
    "freecad": {
      "command": "python",
      "args": [
        "-m",
        "freecad_mcp"
      ]
    }
  }
}

If you installed in a virtual environment, use the full path to Python:

{
  "mcpServers": {
    "freecad": {
      "command": "/path/to/venv/bin/python",
      "args": [
        "-m",
        "freecad_mcp"
      ]
    }
  }
}

4. Restart Claude Desktop

Close and reopen Claude Desktop to load the new MCP server.

Usage

Once configured, you can ask Claude to create 3D models:

Creating Objects

Create a box:

Create a box that is 20mm x 30mm x 10mm tall

Create a cylinder:

Create a cylinder with radius 15mm and height 40mm at position (10, 20, 0)

Create a sphere:

Create a sphere with radius 25mm

Exporting Models

Export to STEP:

Export the model to ~/Desktop/my_model.step

Export to STL:

Export as STL to ~/Desktop/print_me.stl

Available Tools

create_object

Create a 3D primitive object in FreeCAD.

Parameters:

• object_type (required): Type of object - "box", "cylinder", or "sphere"
• dimensions (optional): Object dimensions
  • For box: length, width, height
  • For cylinder: radius, height
  • For sphere: radius
• position (optional): Object position with x, y, z coordinates

Example:

{
  "object_type": "box",
  "dimensions": {
    "length": 20,
    "width": 30,
    "height": 10
  },
  "position": {
    "x": 0,
    "y": 0,
    "z": 0
  }
}

export_file

Export the current FreeCAD document to a file.

Parameters:

• format (required): Export format - "step", "stl", or "obj"
• filepath (required): Output file path (absolute or relative)

Example:

{
  "format": "step",
  "filepath": "~/Desktop/model.step"
}

Architecture

freecad-mcp/
├── freecad_mcp/
│   ├── __init__.py          # Package initialization
│   ├── __main__.py          # Entry point
│   ├── server.py            # MCP server implementation
│   ├── freecad_bridge.py    # FreeCAD interface layer
│   └── tools/
│       ├── __init__.py
│       ├── create_object.py # Object creation tool
│       └── export_file.py   # Export tool
├── setup.py                 # Package setup
├── requirements.txt         # Dependencies
└── README.md               # This file

Development

Running Tests

# Install in development mode
pip install -e .

# Run the server directly
python -m freecad_mcp

Logging

The server logs to stdout. You can monitor activity:

python -m freecad_mcp 2>&1 | tee server.log

Adding New Tools

1. Create a new tool file in freecad_mcp/tools/
2. Implement the tool handler function
3. Register the tool in server.py:
   • Add to list_tools() decorator
   • Add handler in call_tool() decorator

Troubleshooting

FreeCAD Not Found

If you get "FreeCAD not found", ensure it's installed at /Applications/FreeCAD.app or update the paths in freecad_bridge.py.

Import Errors

Make sure you're using the system Python or a virtual environment with access to FreeCAD's libraries.

Server Not Appearing in Claude

1. Check the configuration file path
2. Verify JSON syntax is valid
3. Restart Claude Desktop completely
4. Check Claude's logs for errors

License

MIT License

Contributing

Contributions welcome! Feel free to open issues or submit pull requests.