jhacksman/OpenSCAD-MCP-Server: Devin's attempt at creating an OpenSCAD MCP Server that takes a user prompt and generates a preview image and 3d file.

Devin's attempt at creating an OpenSCAD MCP Server that takes a user prompt and generates a preview image and 3d file. - jhacksman/OpenSCAD-MCP-Server

Summary

OpenSCAD-MCP-Server is a local Model Context Protocol server that turns OpenSCAD source or explicit primitive dimensions into editable SCAD files, STL geometry, and four PNG previews. It lets an MCP-connected assistant write SCAD for complex designs while the server handles compilation and rendering through the locally installed OpenSCAD executable.

What it is useful for

This server is useful for engineers who want an MCP assistant to generate 3D models or quick visual previews without manually running the OpenSCAD CLI. It exposes eight tools: get_capabilities reports the OpenSCAD version and primitive defaults, create_3d_model builds primitives like cube, sphere, cylinder, box, tube, cone, torus, prism, hexagonal_prism, and text, and create_model_from_scad compiles trusted SCAD for custom shapes. modify_3d_model accepts parameter changes or replacement SCAD with an optional expected_revision for optimistic concurrency, get_model_source returns current SCAD and its revision, and export_model writes SCAD, STL, CSG, or 3MF. Dimensions default to millimeters, and a small description parser handles phrases such as "hollow box width 40 mm depth 30 mm height 20 mm thickness 2 mm", supporting mm, cm, m, and inches. Models survive restarts and earlier revisions stay on disk after edits.

How engineers can use it

The README documents the full setup. Install OpenSCAD first (brew install --cask openscad@snapshot on macOS, or sudo apt-get install openscad on Debian/Ubuntu), then clone the repository and run uv sync --locked. Launch the server with uv run openscad-mcp; for HTTP-capable clients, use uv run openscad-mcp --transport http --port 8000 and connect to http://127.0.0.1:8000/mcp. Configure an MCP client to spawn the server with --output-dir set to an absolute path. A typical call to create_3d_model looks like {"model_type": "box", "parameters": {"width": 40, "depth": 30, "height": 20, "thickness": 2}}, while custom designs go through create_model_from_scad with code such as difference() { cube([40,30,8]); translate([20,15,-1]) cylinder(h=10,r=5,$fn=48); }. Documented limitations: only SCAD retains editable parameters since STL, CSG, and 3MF do not preserve parametric relationships; AMF, STEP, OBJ, and 2D exports are not offered; custom SCAD is not sandboxed; each render subprocess times out at 120 seconds; there is no authentication or supported LAN deployment; the project is only verified on macOS arm64 and Ubuntu 24.04 under Xvfb, and Linux headless setups need xvfb-run -a for PNG rendering.