README.md
AI-driven 3D model generation and manipulation using OpenSCAD
3D MCP Server
MCP server for AI-driven 3D model generation using OpenSCAD. Create, combine, transform, and export 3D models through natural language via any MCP-compatible AI client.
Installation
npm install -g @jagjerez-org/3d-mcp-server
Prerequisites
Install OpenSCAD for export and preview rendering:
# Ubuntu/Debian
sudo apt install openscad
# macOS
brew install openscad
# Windows — download from https://openscad.org/downloads.html
Note: OpenSCAD is only required for
exportandpreviewtools. 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):
{
"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:
{
"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
- Scene graph — Objects are tracked in memory with unique IDs
- OpenSCAD codegen — Each operation generates clean OpenSCAD code
- Boolean CSG — Objects combine via union/difference/intersection
- 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
Tools (16)
create_primitiveCreate cube, sphere, cylinder, cone, or toruscreate_textCreate 3D extruded textcreate_polyhedronCreate custom mesh from vertices and facescustom_scadAdd raw OpenSCAD code directlytransformTranslate, rotate, scale, mirror, or color an objectboolean_opUnion, difference, or intersection of multiple objectslinear_extrudeExtrude 2D shape into 3Drotate_extrudeCreate solid of revolution from 2D profilestatusCheck OpenSCAD installation and scene infoscene_listList all objects in the scenescene_clearClear the entire sceneremove_objectRemove a specific objectget_scadGet the full OpenSCAD source codesave_scadSave scene as .scad fileexportExport to STL, OBJ, 3MF, AMF, OFF, DXF, SVG, CSGpreviewRender a PNG preview imageEnvironment Variables
OPENSCAD_BINPath to OpenSCAD binarySCAD_WORK_DIRWorking directory for filesConfiguration
claude_desktop_config.json
{"mcpServers": {"3d": {"command": "3d-mcp-server"}}}Try it
→Create a 30x30x10 box with a 5mm radius hole through the center and export it as STL
→Make a phone stand at 60 degrees and show me a preview
→Create a simple gear with 12 teeth using custom SCAD code
→List all objects currently in the scene and clear them