# FreeCAD MCP Server

> Let AI design 3D models in FreeCAD through natural language.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![FreeCAD 1.1+](https://img.shields.io/badge/FreeCAD-1.1+-green.svg)](https://www.freecad.org/)

**FreeCAD MCP Server** bridges [FreeCAD](https://www.freecad.org/) and AI assistants via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). It exposes 39 CAD tools that let AI agents create, modify, query, and export 3D models — all through natural language conversation.

## Why?

Traditional CAD requires learning complex software UIs. With FreeCAD MCP, you can:

- **Design by conversation** — describe what you want, AI builds it
- **Iterate rapidly** — tweak dimensions, add features, and compare variants in seconds
- **Automate repetitive tasks** — parameterized modeling without clicking through menus
- **Integrate into workflows** — connect CAD with code review, documentation, and CI/CD

## Demo

Tell your AI assistant:

> "Create a 100x60x20mm enclosure base with 2mm wall thickness and a central screen cutout"

The AI will call FreeCAD tools automatically:

```
new_document → create_box(100, 60, 20) → create_box(96, 56, 18)
→ translate → boolean_cut → export_step("enclosure_base.step")
```

## Quick Start

### 1. Install

```bash
git clone https://github.com/your-username/freecad-mcp.git
cd freecad-mcp
```

### 2. Install MCP dependencies with FreeCAD's Python

```bash
# macOS
/Applications/FreeCAD.app/Contents/Resources/bin/python -m pip install -r requirements.txt

# Windows
E:\Freecad\bin\python.exe -m pip install -r requirements.txt

# Linux (adjust path to your FreeCAD installation)
freecadpython -m pip install -r requirements.txt
```

> **Important:** You must use FreeCAD's bundled Python, not the system Python. FreeCAD's `FreeCAD.so`/`FreeCAD.pyd` is a C++ extension that only loads in FreeCAD's Python environment.

### 3. Configure your MCP client

#### opencode

Add to `~/.config/opencode/opencode.json`:

```json
{
  "mcp": {
    "freecad-modeling": {
      "type": "local",
      "command": ["bash", "/path/to/freecad-mcp/run_mcp.sh"],
      "enabled": true
    }
  }
}
```

#### Claude Desktop / Cline / Cursor

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "freecad-modeling": {
      "command": "bash",
      "args": ["/path/to/freecad-mcp/run_mcp.sh"],
      "cwd": "/path/to/freecad-mcp"
    }
  }
}
```

**Windows users:** Replace `bash` with the path to `run_server.bat`.

### 4. Restart your client

The FreeCAD tools will now be available in your AI conversations.

## Available Tools (39)

### Document Management
| Tool | Description |
|------|-------------|
| `new_document` | Create a new FreeCAD document |
| `open_document` | Open an existing .FCStd file |
| `save_document` | Save the current document |
| `close_document` | Close a document |
| `list_documents` | List all open documents |
| `list_objects` | List objects in a document |
| `get_active_document` | Get active document info |

### Primitive Shapes
| Tool | Description |
|------|-------------|
| `create_box` | Create a rectangular box (L×W×H) |
| `create_cylinder` | Create a cylinder |
| `create_sphere` | Create a sphere |
| `create_cone` | Create a cone or frustum |
| `create_torus` | Create a torus (donut shape) |
| `create_prism` | Create a regular polygon prism |
| `create_hollow_cylinder` | Create a hollow cylinder (pipe) |

### Boolean Operations
| Tool | Description |
|------|-------------|
| `boolean_cut` | Subtract one shape from another |
| `boolean_fuse` | Merge two shapes into one |
| `boolean_intersect` | Keep only overlapping volume |
| `boolean_compound` | Group shapes without merging |

### Transforms
| Tool | Description |
|------|-------------|
| `translate` | Move an object by dx/dy/dz |
| `rotate` | Rotate around an arbitrary axis |
| `mirror` | Mirror across XY/XZ/YZ plane |
| `scale_object` | Scale uniformly from a center point |
| `set_placement` | Set exact position and orientation |

### Sketch & Features
| Tool | Description |
|------|-------------|
| `create_sketch_extrude` | Extrude a 2D profile into a solid |
| `create_sketch_revolve` | Revolve a 2D profile into a solid |
| `fillet_edges` | Round edges with a radius |
| `chamfer_edges` | Bevel edges at 45° |

### Measurement & Inspection
| Tool | Description |
|------|-------------|
| `get_object_info` | Get type, label, placement, and geometry |
| `measure_volume` | Measure volume in mm³ |
| `measure_area` | Measure surface area in mm² |
| `bounding_box` | Get axis-aligned bounding box |
| `center_of_mass` | Get center of mass coordinates |
| `check_validity` | Verify geometry is valid |

### Export
| Tool | Description |
|------|-------------|
| `export_step` | Export to STEP (best for interoperability) |
| `export_stl` | Export to STL (for 3D printing) |
| `export_obj` | Export to OBJ (for rendering/mesh) |
| `export_brep` | Export to BREP (Open CASCADE native) |
| `export_iges` | Export to IGES (legacy CAD exchange) |
| `save_fcstd` | Save as FreeCAD native .FCStd |

## Example Workflows

### Enclosure with mounting holes

> "Design a 120×80×25mm electronics enclosure. Base should have 2mm walls, internal ribs for PCB mounting, and four M3 screw posts in the corners. Top should be a flat lid with matching screw holes. Export both as STEP."

### Parametric bracket

> "Create an L-shaped bracket, 50mm on each leg, 5mm thick, with a 10mm fillet on the inner corner and two M4 through-holes on each leg. Measure the volume and export as STL."

### Mechanical part with revolve

> "Create a shaft collar by revolving a profile: 15mm outer diameter, 8mm bore, 12mm wide, with a 1mm chamfer on both edges. Export as STEP."

## Project Structure

```
freecad-mcp/
├── main.py                 # Entry point
├── freecad_mcp/
│   ├── server.py           # MCP server + tool registration
│   ├── runner.py           # Safe execution wrapper
│   └── tools/
│       ├── document.py     # Document management
│       ├── primitives.py   # Shape creation
│       ├── boolean.py      # Boolean operations
│       ├── transform.py    # Transforms
│       ├── sketch.py       # Sketch features
│       ├── measure.py      # Measurement
│       └── export.py       # File export
├── run_mcp.sh              # macOS/Linux launcher
├── run_server.bat          # Windows launcher
├── requirements.txt        # Python dependencies
└── README.md
```

## Requirements

| Component | Version |
|-----------|---------|
| FreeCAD | 1.1 or later |
| Python | FreeCAD's bundled Python (3.11+) |
| MCP SDK | `mcp>=1.28.0` |

## Configuration

### Custom FreeCAD path

Edit `run_mcp.sh` (macOS/Linux) or `run_server.bat` (Windows) to point to your FreeCAD Python installation.

### Units

All dimensions are in **millimeters (mm)**. The coordinate system is right-handed with Z-axis pointing up.

## Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/my-feature`)
3. Make your changes
4. Run the smoke test: `/Applications/FreeCAD.app/Contents/Resources/bin/python scripts/test_basic.py`
5. Submit a pull request

### Ideas for contributions

- Add new tools (e.g., pattern arrays, surface operations, assembly)
- Improve error handling and validation
- Add support for FreeCAD 1.0 (earlier Python versions)
- Create example projects / tutorials
- Add unit tests

## License

[MIT](LICENSE)

## Acknowledgments

- [FreeCAD](https://www.freecad.org/) — The open-source parametric 3D CAD modeler
- [Model Context Protocol](https://modelcontextprotocol.io/) — The protocol for AI-tool integration
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) — Official Python implementation