Skip to content
Back to search

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/jhacksman/OpenSCAD-MCP-Server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/jhacksman/OpenSCAD-MCP-Server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jhacksman--openscad-mcp-server/badge.svg)](/listings/jhacksman--openscad-mcp-server)

HTML

<a href="/listings/jhacksman--openscad-mcp-server"><img src="/api/listings/jhacksman--openscad-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires Python 3.11+ and OpenSCAD. No API keys, CUDA, Open3D, or separate image renderer are required.

Install OpenSCAD using the [official downloads](https://openscad.org/downloads.html). On macOS, the current native Apple Silicon/Intel build is available with:

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 `OPENSCAD_EXECUTABLE` to the full path of `openscad.exe`.

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:

export UV_PROJECT_ENVIRONMENT="$HOME/.cache/openscad-mcp-venv"
uv sync --locked

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 154 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # OpenSCAD MCP Server
  2. 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.
  3. **Status:** the supported implementation is in `src/openscad_mcp`. The previous image generation, CUDA reconstruction, remote processing, and printer code is archived in [`legacy/`](legacy/README.md). It is unfinished and is not part of the installed server. See the [audit and machine test results](docs/audit.md).
  4. ## Install
  5. Requires Python 3.11+ and OpenSCAD. No API keys, CUDA, Open3D, or separate image renderer are required.
  6. Install OpenSCAD using the [official downloads](https://openscad.org/downloads.html). On macOS, the current native Apple Silicon/Intel build is available with:
  7. ```sh
  8. brew install --cask openscad@snapshot
  9. openscad --version
  10. ```
  11. 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 `OPENSCAD_EXECUTABLE` to the full path of `openscad.exe`.
  12. ```sh
  13. git clone https://github.com/jhacksman/OpenSCAD-MCP-Server.git
  14. cd OpenSCAD-MCP-Server
  15. uv sync --locked
  16. uv run openscad-mcp --help
  17. ```
  18. 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.
  19. On an external filesystem that cannot create symlinks, put the environment on the internal disk:
  20. ```sh
  21. export UV_PROJECT_ENVIRONMENT="$HOME/.cache/openscad-mcp-venv"
  22. uv sync --locked
  23. ```
  24. ## Docker and Jetson
  25. A headless stdio image is available through the root `Dockerfile`. See [Docker setup and verification](docs/docker.md) for build commands, MCP client configuration, persistent model storage, and Glama listing requirements. The image needs no GPU.
  26. For the hardware question in issue #19, see [Jetson Orin Nano and CUDA](docs/jetson.md). The supported server does not use CUDA; the archived reconstruction prototype is not restored by this Docker support.
  27. ## Connect an MCP client
  28. Stdio is the default. Configure the client to launch the server process, using absolute paths:
  29. ```json
  30. {
  31. "mcpServers": {
  32. "openscad": {
  33. "command": "/absolute/path/to/venv/bin/openscad-mcp",
  34. "args": ["--output-dir", "/absolute/path/to/models"]
  35. }
  36. }
  37. }
  38. ```
  39. For clients supporting Streamable HTTP:
  40. ```sh
  41. uv run openscad-mcp --transport http --port 8000
  42. ```
  43. 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 `get_model_preview`; there is no HTTP listener.
  44. ## Tools
  45. | Tool | Purpose |
  46. | --- | --- |
  47. | `get_capabilities` | OpenSCAD version and supported primitives with default parameters |
  48. | `create_3d_model` | Create a primitive using `model_type` and `parameters`, or a limited description |
  49. | `create_model_from_scad` | Compile trusted `scad_code` for a custom 3D model |
  50. | `modify_3d_model` | Change primitive parameters or replace a model's `scad_code` |
  51. | `get_model` | Read a saved model and its artifact paths |
  52. | `get_model_source` | Read saved SCAD source and its revision, including inside Docker |
  53. | `get_model_preview` | Return a PNG image as MCP image content |
  54. | `export_model` | Export `scad`, `stl`, `csg`, or `3mf` |
  55. Example arguments to `create_3d_model`:
  56. ```json
  57. {
  58. "model_type": "box",
  59. "parameters": {"width": 40, "depth": 30, "height": 20, "thickness": 2}
  60. }
  61. ```
  62. Dimensions are in millimeters. Supported types: `cube` (also rectangular blocks), `sphere`, `cylinder`, `box` (open hollow box), `rounded_box` (solid), `tube`, `cone`, `torus`, `prism` (right triangular cross-section), `hexagonal_prism`, and `text`. Call `get_capabilities` for each type's exact parameter names. A torus uses the radius to the tube center (`major_radius`) and the tube radius (`minor_radius`).
  63. The optional description parser recognizes named dimensions such as `hollow box width 40 mm depth 30 mm height 20 mm thickness 2 mm` or `cube 2 cm wide 1 inch high`. It supports mm, cm, m, and inches; omitted units mean mm. It is a small parser, not a general natural-language model. Unspecified dimensions use the returned defaults. Prefer explicit parameters for precision. For arbitrary objects, have the assistant write self-contained SCAD and call `create_model_from_scad`.
  64. ```json
  65. {
  66. "scad_code": "difference() { cube([40,30,8]); translate([20,15,-1]) cylinder(h=10,r=5,$fn=48); }",
  67. "description": "Mounting plate with a through hole"
  68. }
  69. ```
  70. To modify a primitive:
  71. ```json
  72. {"model_id": "ID_FROM_CREATION", "parameters": {"height": 25}}
  73. ```
  74. For custom models, call `get_model_source` with the model ID to retrieve `scad_code` and `revision` directly through MCP. Edit the returned source, then call `modify_3d_model` with the new `scad_code` and `expected_revision` set to the revision you read. No access to the server's filesystem is needed to read the source.
  75. The same optional revision check works for primitive parameter edits:
  76. ```json
  77. {
  78. "model_id": "ID_FROM_CREATION",
  79. "parameters": {"height": 25},
  80. "expected_revision": "REVISION_FROM_GET_MODEL"
  81. }
  82. ```
  83. If another edit has already committed, the operation fails before rendering or changing files. MCP reports a tool error; the HTTP `/tool_call` API returns **409** with `current_revision`. Read the latest source/parameters and incorporate the intervening changes before retrying. Omitting `expected_revision` preserves the original unconditional edit behavior.
  84. Only **SCAD** retains editable source parameters. CSG is an evaluated geometry tree. STL and 3MF are meshes; they do not preserve the design's parametric relationships. AMF (removed in current OpenSCAD builds), STEP, OBJ, 2D exports, image reconstruction, and printing are not offered.
  85. ## HTTP smoke test
  86. With the HTTP server running:
  87. ```sh
  88. curl --fail http://127.0.0.1:8000/tool_call \
  89. -H 'Content-Type: application/json' \
  90. -d '{"tool_name":"create_3d_model","tool_params":{"model_type":"box","parameters":{"width":40,"depth":30,"height":20,"thickness":2}}}'
  91. ```
  92. Open the returned `preview_url` on the same server. Download `/download/MODEL_ID?format=stl` or `?format=scad`. `/tool_call` is a convenience JSON API, separate from the actual MCP protocol at `/mcp`. Image retrieval over this API uses `/preview/VIEW/MODEL_ID`.
  93. ## Behavior and limits
  94. - Creation succeeds only after a real STL and all four PNGs have been generated. Renderer failures, empty output, and OpenSCAD warnings/errors are reported as failures; no placeholder geometry or preview is substituted.
  95. - Edits create a new revision and update the manifest only after successful rendering. Earlier revisions remain on disk. Models survive server restarts.
  96. - Default storage is `~/.local/share/openscad-mcp/models`. Override with `--output-dir` or `OPENSCAD_OUTPUT_DIR`. Each render subprocess has a 120-second timeout, configurable with `--timeout`. A model requires five subprocesses, so the total request can take longer.
  97. - Run one server process per output directory. Renders and edits are serialized. There is no automatic disk cleanup, distributed job queue, or multi-process store coordination.
  98. - This is a trusted local tool. Custom SCAD executes with the current user's file access, including OpenSCAD `import`, `include`, and `use`; it is not sandboxed. HTTP binds to loopback and rejects non-local Host/Origin headers. There is no authentication or supported public/LAN deployment.
  99. - Tested locally on macOS arm64 and in Ubuntu 24.04 CI under Xvfb. Windows and other platform/display combinations are unverified. No hardware printer or remote GPU was exercised.
  100. ## Development and verification
  101. ```sh
  102. uv sync --locked --group dev
  103. uv run ruff check src/openscad_mcp tests scripts
  104. uv run ruff format --check src/openscad_mcp tests scripts
  105. uv run pytest -q
  106. ```
  107. The full suite requires OpenSCAD and fails if it is unavailable. Tests launch real stdio and HTTP server processes, use the official MCP client, download exports, decode PNGs, inspect mesh topology/dimensions/volume, test persistence and failed edits, and exercise invalid requests. `uv run pytest -m 'not integration'` runs the unit checks only and does not establish end-to-end correctness.
  108. ## License
  109. [MIT](LICENSE), copyright 2026 Jack Hacksman.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.