# FreeCAD MCP Server
[![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/)
[![GitHub release](https://img.shields.io/github/v/release/Coben-3d/freecad-mcp)](https://github.com/Coben-3d/freecad-mcp/releases)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)

> Model Context Protocol server for FreeCAD - Connect Claude AI to FreeCAD for AI-powered 3D modeling
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![GitHub release](https://img.shields.io/github/v/release/Coben-3d/freecad-mcp)](https://github.com/Coben-3d/freecad-mcp/releases)

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](https://www.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:

```bash
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:

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

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

```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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

```bash
# 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:

```bash
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.