# FreeCAD MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with FreeCAD for 3D modeling and CAD operations.

## Features

- **Basic Geometry Creation**: Create boxes, cylinders, spheres with specified dimensions
- **Boolean Operations**: Perform union, cut, and common operations between objects
- **Document Management**: Save documents and list objects
- **Custom Script Execution**: Execute arbitrary Python scripts in FreeCAD context
- **Cross-Platform**: Supports Windows, macOS, and Linux

## Prerequisites

1. **FreeCAD Installation**: Install FreeCAD from [freecad.org](https://www.freecad.org/)
2. **Node.js**: Version 18 or higher
3. **TypeScript**: For development

## Installation

1. Clone this repository:
```bash
git clone https://github.com/lucygoodchild/freecad-mcp-server.git
cd freecad-mcp-server
```

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
npm run build
```

4. Configure FreeCAD path (if needed):
   - The server attempts to auto-detect FreeCAD installation
   - Default paths:
     - Windows: `C:\Program Files\FreeCAD 0.21\bin\FreeCAD.exe`
     - macOS: `/Applications/FreeCAD.app/Contents/MacOS/FreeCAD`
     - Linux: `/usr/bin/freecad`

## Usage

### Running the Server

```bash
npm start
```

### Claude Desktop
Add the following to your MCP client configuration (~/Library/Application Support/Claude/claude_desktop_config.json):
{
  "mcpServers": {
    "freecad-mcp-server": {
        "command": "node",
          "args": ["/path/to/free-cad-mcp/build/index.js"]
          }
      }
}
Make sure to replace "/path/to/free-cad-mcp/build/index.js" with the actual path and to restart Claude once you have made the changes

### Available Tools

#### `create_box`
Create a rectangular box with specified dimensions.
```json
{
  "name": "create_box",
  "arguments": {
    "length": 50,
    "width": 30,
    "height": 20,
    "name": "MyBox"
  }
}
```

#### `create_cylinder`
Create a cylinder with specified radius and height.
```json
{
  "name": "create_cylinder", 
  "arguments": {
    "radius": 10,
    "height": 50,
    "name": "MyCylinder"
  }
}
```

#### `create_sphere`
Create a sphere with specified radius.
```json
{
  "name": "create_sphere",
  "arguments": {
    "radius": 15,
    "name": "MySphere"
  }
}
```

#### `boolean_operation`
Perform boolean operations between two objects.
```json
{
  "name": "boolean_operation",
  "arguments": {
    "operation": "union",
    "object1": "Box",
    "object2": "Cylinder",
    "result_name": "Combined"
  }
}
```

Operations: `union`, `cut`, `common`

#### `save_document`
Save the current FreeCAD document.
```json
{
  "name": "save_document",
  "arguments": {
    "filename": "my_model.FCStd",
    "path": "/path/to/save"
  }
}
```

#### `list_objects`
List all objects in the current document.
```json
{
  "name": "list_objects",
  "arguments": {}
}
```

#### `execute_python_script`
Execute custom Python script in FreeCAD context.
```json
{
  "name": "execute_python_script",
  "arguments": {
    "script": "box = doc.addObject('Part::Box', 'CustomBox')\nbox.Length = 100"
  }
}
```

## Integration with AI Assistants

This server implements the Model Context Protocol, making it compatible with MCP-enabled AI assistants. The AI can:

1. **Generate 3D Models**: Create complex geometries by combining basic shapes
2. **Parametric Design**: Modify dimensions and parameters based on requirements
3. **Assembly Creation**: Build multi-part assemblies using boolean operations
4. **Design Automation**: Execute complex modeling workflows through scripting

### Example AI Interactions

- "Create a bearing housing with a 20mm inner diameter and 40mm outer diameter"
- "Make a threaded bolt with M6 threading, 50mm long"
- "Design a simple bracket to hold two 10mm rods 30mm apart"

## Development

### Project Structure
```
src/
  index.ts          # Main server implementation
build/              # Compiled JavaScript output
package.json        # Dependencies and scripts
tsconfig.json       # TypeScript configuration
```

### Building
```bash
npm run build
```

### Development Mode
```bash
npm run dev
```

## Troubleshooting

### FreeCAD Not Found
- Verify FreeCAD is installed and accessible from command line
- Update the `freecadPath` in the server constructor if needed
- Check that the FreeCAD executable has proper permissions

### Script Execution Errors
- Ensure FreeCAD Python environment has required modules
- Check script syntax - Python scripts are executed in FreeCAD's Python interpreter
- Use `list_objects` to verify object names before boolean operations