jhacksman/OpenSCAD-MCP-Server

A local MCP server that turns OpenSCAD source or explicit primitive dimensions into editable SCAD, STL geometry, and four PNG previews. The connected assistant can write SCAD for complex designs; this server compiles and renders it with the installed OpenSCAD executable.
Status: the supported implementation is in src/openscadmcp. The previous image generation, CUDA reconstruction, remote processing, and printer code is archived in legacy/. It is unfinished and is not part of the installed server. See the audit and machine test results.
## Install
Requires Python 3.11+ and OpenSCAD. No API keys, CUDA, Open3D, or separate image renderer are required.
Install OpenSCAD using the official downloads. On macOS, the current native Apple Silicon/Intel build is available with:
sh
brew install --cask openscad@snapshot
openscad --version
On Debian/Ubuntu, sudo apt-get install openscad installs the distribution package. Linux PNG rendering may need an X display; use xvfb-run -a around the server or tests on a headless machine. Windows users can set OPENSCADEXECUTABLE to the full path of openscad.exe.
sh
git clone https://github.com/jhacksman/OpenSCAD-MCP-Server.git
cd OpenSCAD-MCP-Server
uv sync --locked
uv run openscad-mcp --help
Alternatively, install into a virtual environment with python -m pip install . and run openscad-mcp. requirements.txt installs this same package. uv.lock pins the tested dependency resolution; the project metadata permits compatible updates.
On an external filesystem that cannot create symlinks, put the environment on the internal disk:
sh
export UVPROJECTENVIRONMENT="$HOME/.cache/openscad-mcp-venv"
uv sync --locked
## Docker and Jetson
A headless stdio image is available through the root Dockerfile. See Docker setup and verification for build commands, MCP client configuration, persistent model storage, and Glama listing requirements. The image needs no GPU.
For the hardware question in issue #19, see Jetson Orin Nano and CUDA. The supported server does not use CUDA; the archived reconstruction prototype is not restored by this Docker support.
## Connect an MCP client
Stdio is the default. Configure the client to launch the server process, using absolute paths:
json
"mcpServers": {
"openscad": {
"command": "/absolute/path/to/venv/bin/openscad-mcp",
"args": ["--output-dir", "/absolute/path/to/models"]
For clients supporting Streamable HTTP:
sh
uv run openscad-mcp --transport http --port 8000
The MCP endpoint is http://127.0.0.1:8000/mcp. / is server information; /health reports the OpenSCAD version and primitive defaults. HTTP also serves preview pages and downloads. In stdio mode, use returned absolute file paths or getmodelpreview; there is no HTTP listener.
## Tools
| Tool | Purpose |
| getcapabilities | OpenSCAD version and supported primitives with default parameters |
| create3dmodel | Create a primitive using modeltype and parameters, or a limited description |
| createmodelfromscad | Compile trusted scadcode for a custom 3D model |
| modify3dmodel | Change primitive parameters or replace a model's scadcode |
| getmodel | Read a saved model and its artifact paths |
| getmodelsource | Read saved SCAD source and its revision, including inside Docker |