# 3D MCP Server

MCP server for AI-driven 3D model generation using [OpenSCAD](https://openscad.org). Create, combine, transform, and export 3D models through natural language via any MCP-compatible AI client.

## Installation

```bash
npm install -g @jagjerez-org/3d-mcp-server
```

### Prerequisites

Install OpenSCAD for export and preview rendering:

```bash
# Ubuntu/Debian
sudo apt install openscad

# macOS
brew install openscad

# Windows — download from https://openscad.org/downloads.html
```

> **Note:** OpenSCAD is only required for `export` and `preview` tools. Scene building and SCAD code generation work without it.

## Quick Start

### With Claude Desktop

Add to your Claude Desktop config (`~/.config/claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "3d": {
      "command": "3d-mcp-server"
    }
  }
}
```

Then ask Claude: *"Create a box with a cylindrical hole through the center and export it as STL"*

### With Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "3d": {
      "command": "3d-mcp-server"
    }
  }
}
```

## Tools

### Primitives

| Tool | Description |
|------|-------------|
| `create_primitive` | Create cube, sphere, cylinder, cone, or torus |
| `create_text` | Create 3D extruded text |
| `create_polyhedron` | Create custom mesh from vertices and faces |
| `custom_scad` | Add raw OpenSCAD code directly |

### Transformations

| Tool | Description |
|------|-------------|
| `transform` | Translate, rotate, scale, mirror, or color an object |

### Boolean Operations

| Tool | Description |
|------|-------------|
| `boolean_op` | Union, difference, or intersection of multiple objects |

### Extrusions

| Tool | Description |
|------|-------------|
| `linear_extrude` | Extrude 2D shape (circle, square, polygon) into 3D |
| `rotate_extrude` | Create solid of revolution from 2D profile |

### Scene Management

| Tool | Description |
|------|-------------|
| `status` | Check OpenSCAD installation and scene info |
| `scene_list` | List all objects in the scene |
| `scene_clear` | Clear the entire scene |
| `remove_object` | Remove a specific object |

### Output

| Tool | Description |
|------|-------------|
| `get_scad` | Get the full OpenSCAD source code |
| `save_scad` | Save scene as .scad file |
| `export` | Export to STL, OBJ, 3MF, AMF, OFF, DXF, SVG, CSG |
| `preview` | Render a PNG preview image |

## Examples

### Box with hole

```
AI: "Create a 30x30x10 box with a 5mm radius hole through the center"

→ create_primitive(shape: "cube", width: 30, depth: 30, height: 10)
→ create_primitive(shape: "cylinder", radius: 5, height: 12)
→ boolean_op(operation: "difference", objectIds: ["abc", "def"])
→ export(format: "stl")
```

### Phone stand

```
AI: "Make a phone stand at 60 degrees"

→ create_primitive(shape: "cube", width: 80, depth: 50, height: 5, name: "base")
→ create_primitive(shape: "cube", width: 80, depth: 5, height: 100, name: "back")
→ transform(objectId: "...", operation: "rotate", x: -60)
→ boolean_op(operation: "union", objectIds: [...])
→ preview()
→ export(format: "stl")
```

### Gear

```
AI: "Create a simple gear with 12 teeth"

→ custom_scad(code: "...", name: "gear")
→ preview()
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `OPENSCAD_BIN` | `openscad` | Path to OpenSCAD binary |
| `SCAD_WORK_DIR` | `/tmp/3d-mcp-work` | Working directory for files |

## How It Works

1. **Scene graph** — Objects are tracked in memory with unique IDs
2. **OpenSCAD codegen** — Each operation generates clean OpenSCAD code
3. **Boolean CSG** — Objects combine via union/difference/intersection
4. **Export** — OpenSCAD CLI renders the final SCAD to STL/PNG/etc.

The AI builds models step by step: create shapes → transform → combine → export.

## License

MIT