# OpenSCAD MCP Server

An MCP (Model Context Protocol) server that enables LLMs to create and manipulate 3D models using OpenSCAD.

## Why OpenSCAD?

OpenSCAD's code-based CSG (Constructive Solid Geometry) approach is ideal for LLM integration:
- **Text-based**: Models are defined in code, not GUI interactions
- **Deterministic**: Same code always produces same geometry
- **Composable**: CSG operations (union, difference, hull) map naturally to how LLMs describe shapes
- **Parametric**: Easy to create adjustable designs

## Features

| Tool | Description |
|------|-------------|
| `openscad_create_model` | Create a new .scad model file |
| `openscad_update_model` | Update existing model code |
| `openscad_get_model` | Retrieve model source code |
| `openscad_list_models` | List all models in workspace |
| `openscad_delete_model` | Delete a model |
| `openscad_render_preview` | Generate PNG preview image |
| `openscad_render_code` | Render code directly without saving |
| `openscad_export` | Export to STL, 3MF, AMF, etc. |
| `openscad_get_info` | Get OpenSCAD version and config |

## Installation

### Prerequisites

1. **OpenSCAD** must be installed. Default path: `C:\Program Files\OpenSCAD\openscad.exe`
   - Download from: https://openscad.org/downloads.html

2. **Python 3.10+** with pip

### Install the MCP Server

```bash
cd openscad-mcp
pip install -e .
```

### Configure Claude Desktop

Add to your Claude Desktop config (`%APPDATA%\Claude\claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "openscad": {
      "command": "openscad-mcp"
    }
  }
}
```

Or if you installed in development mode and want to specify the path:

```json
{
  "mcpServers": {
    "openscad": {
      "command": "python",
      "args": ["-m", "openscad_mcp.server"]
    }
  }
}
```

## Usage Examples

### Simple Cube
```openscad
cube([20, 20, 20], center=true);
```

### Rounded Box
```openscad
$fn = 32;
minkowski() {
    cube([20, 20, 10], center=true);
    sphere(r=2);
}
```

### Hollow Cylinder
```openscad
$fn = 64;
difference() {
    cylinder(h=30, r=15);
    translate([0, 0, -1])
        cylinder(h=32, r=12);
}
```

### Parametric Design
```openscad
// Parameters
wall_thickness = 2;
inner_diameter = 30;
height = 50;

$fn = 64;

difference() {
    cylinder(h=height, d=inner_diameter + wall_thickness*2);
    translate([0, 0, wall_thickness])
        cylinder(h=height, d=inner_diameter);
}
```

## Workspace

Models are stored in `./workspace/` relative to the server. The workspace is created automatically on first run.

## Export Formats

- **STL**: Standard format for 3D printing
- **3MF**: Modern 3D printing format with materials support
- **AMF**: Additive Manufacturing File Format
- **OFF**: Object File Format
- **DXF/SVG**: 2D exports for laser cutting, etc.
- **PNG**: Rendered images

## Camera Control

Preview renders support camera positioning:

- **Rotation mode**: `translate_x,translate_y,translate_z,rot_x,rot_y,rot_z,distance`
  - Example: `"0,0,0,45,0,30,200"` - view from 45° elevation, 30° rotation

- **Eye/center mode**: `eye_x,eye_y,eye_z,center_x,center_y,center_z`
  - Example: `"100,100,100,0,0,0"` - camera at (100,100,100) looking at origin

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run directly
python -m openscad_mcp.server
```

## License

MIT