# 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
