Content
# FreeCAD MCP Server
Let AI (such as Cline, Cursor, opencode) directly call FreeCAD for 3D modeling through the MCP protocol.
## Overview
This project is a **MCP (Model Context Protocol) Server**, which encapsulates the Python API of FreeCAD and provides 39 modeling tools, allowing AI to:
- Create/edit/query 3D models
- Perform boolean operations (cutting, merging, intersection)
- Transform objects (translation, rotation, mirroring, scaling)
- Extrude/rotate sketches to create solids
- Measure geometric properties (volume, area, centroid, bounding box)
- Export in STEP / STL / OBJ / BREP / IGES / FCStd formats
## Requirements
| Component | Requirement |
|------|------|
| FreeCAD | 1.1.x or higher |
| Python | FreeCAD's built-in Python (not system Python) |
| MCP SDK | `mcp>=1.28.0` |
> **Important**: Must use FreeCAD's built-in Python because `FreeCAD.pyd` / `FreeCAD.so` is a C++ extension that can only be loaded in FreeCAD's Python environment.
## Quick Start
### 1. Clone the Project
```bash
git clone https://github.com/your-username/freecad-mcp.git
cd freecad-mcp
```
### 2. Install MCP Dependencies
```bash
# macOS / Linux
/Applications/FreeCAD.app/Contents/Resources/bin/python -m pip install mcp
# Windows
E:\Freecad\bin\python.exe -m pip install mcp
```
### 3. Configure MCP Client
#### opencode
Add the following to `~/.config/opencode/opencode.json`:
```json
{
"mcp": {
"freecad-modeling": {
"type": "local",
"command": ["bash", "/path/to/freecad-mcp/run_mcp.sh"],
"enabled": true
}
}
}
```
#### Cline / Cursor
```json
{
"mcpServers": {
"freecad-modeling": {
"command": "bash",
"args": ["/path/to/freecad-mcp/run_mcp.sh"],
"cwd": "/path/to/freecad-mcp"
}
}
}
```
> **Windows Users**: Use `run_server.bat` instead of `run_mcp.sh`
### 4. Restart MCP Client
After configuration, restart the client to enable AI to use FreeCAD modeling tools in conversations.
## Example Usage
Tell AI:
> "Help me create a 20×15×10 box, then drill a radius 3 hole in the center, and export as a STEP file."
AI will automatically call:
1. `new_document` → Create a new document
2. `create_box(20, 15, 10)` → Create a box
3. `create_cylinder(3, 10)` → Create a cylinder
4. `translate("Cylinder", 10, 7.5, 0)` → Move to center
5. `boolean_cut("Box", "Cylinder")` → Perform boolean cutting
6. `export_step("output/part.step")` → Export
## Available Tools (39)
### Document Management
| Tool | Description |
|------|------|
| `new_document` | Create a new document |
| `open_document` | Open a .FCStd file |
| `save_document` | Save a 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 information |
### Primitive Creation
| Tool | Description |
|------|------|
| `create_box` | Create a cuboid |
| `create_cylinder` | Create a cylinder |
| `create_sphere` | Create a sphere |
| `create_cone` | Create a cone/frustum |
| `create_torus` | Create a torus |
| `create_prism` | Create a prism |
### Boolean Operations
| Tool | Description |
|------|------|
| `boolean_cut` | Difference (cutting) |
| `boolean_fuse` | Union (merging) |
| `boolean_intersect` | Intersection |
| `boolean_compound` | Compound |
### Transformation Tools
| Tool | Description |
|------|------|
| `translate` | Translation |
| `rotate` | Rotation |
| `mirror` | Mirroring |
| `scale_object` | Scaling |
| `set_placement` | Set position + orientation |
### Query/Measurement
| Tool | Description |
|------|------|
| `get_object_info` | Get object information |
| `measure_volume` | Measure volume |
| `measure_area` | Measure surface area |
| `bounding_box` | Get bounding box |
| `center_of_mass` | Get center of mass |
| `check_validity` | Check geometric validity |
### Export
| Tool | Description |
|------|------|
| `export_step` | Export STEP |
| `export_stl` | Export STL |
| `export_obj` | Export OBJ |
| `export_brep` | Export BREP |
| `export_iges` | Export IGES |
| `save_fcstd` | Save as FCStd |
### Sketch Features
| Tool | Description |
|------|------|
| `create_sketch_extrude` | Extrude sketch |
| `create_sketch_revolve` | Revolve sketch |
| `create_hollow_cylinder` | Create hollow cylinder |
| `fillet_edges` | Fillet edges |
| `chamfer_edges` | Chamfer edges |
## Project Structure
```
freecad-mcp/
├── main.py # Entry point
├── freecad_mcp/
│ ├── __init__.py
│ ├── server.py # MCP server + tool registration
│ ├── runner.py # Secure execution + JSON encapsulation
│ └── tools/
│ ├── document.py # Document management
│ ├── primitives.py# Primitive creation
│ ├── boolean.py # Boolean operations
│ ├── transform.py # Transformation
│ ├── measure.py # Query/measurement
│ ├── export.py # Export
│ └── sketch.py # Sketch features
├── scripts/
│ └── test_basic.py # Smoke test
├── output/ # Export file output directory
├── run_mcp.sh # macOS/Linux startup script
├── run_server.bat # Windows startup script
├── requirements.txt
└── README.md
```
## Technical Notes
- **Transmission Method**: stdio (standard MCP transmission)
- **Runtime Environment**: FreeCAD's built-in Python, 3.11+
- **No GUI Mode**: Server runs in no GUI environment, exporting uses Part module
- **Units**: All dimensions default to millimeters (mm)
- **Coordinate System**: Right-hand coordinate system, Z-axis upward
## FAQs
### Q: Why not use system Python?
FreeCAD's Python extension is compiled in C++ and only compatible with FreeCAD's built-in Python environment. System Python cannot `import FreeCAD`.
### Q: How to find FreeCAD Python on macOS?
Usually located at:
```
/Applications/FreeCAD.app/Contents/Resources/bin/python
```
### Q: How to modify FreeCAD installation path?
Edit `run_mcp.sh` (macOS/Linux) or `run_server.bat` (Windows) and modify the Python path.
### Q: Exporting STL/OBJ fails?
Ensure using `freecadcmd` or correctly configuring `PYTHONPATH`. Code handles export in no GUI environment.
## License
MIT
