Skip to content
Back to search

openscad-mcp

A Model Context Protocol (MCP) server for OpenSCAD 3D modeling and rendering

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

Its scripts were only partly scanned.

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/RobertCoop/openscad-mcp 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/RobertCoop/openscad-mcp'

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/robertcoop--openscad-mcp/badge.svg)](/listings/robertcoop--openscad-mcp)

HTML

<a href="/listings/robertcoop--openscad-mcp"><img src="/api/listings/robertcoop--openscad-mcp/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.

The server is published on PyPI as `openscad-mcp`, so [uv](https://docs.astral.sh/uv/) runs it with no clone and no virtualenv: `uvx openscad-mcp`. uv keeps a cached copy; `uv tool upgrade openscad-mcp` (or `uvx openscad-mcp@latest`) pulls a new release, and `uvx openscad-mcp@0.6.1` pins one.

Claude Code

Add the server with a single command:

claude mcp add openscad --transport stdio -- uvx openscad-mcp

Or, if OpenSCAD is not on your PATH:

claude mcp add openscad --transport stdio \
  --env OPENSCAD_PATH=/path/to/openscad -- uvx openscad-mcp

Use the `--scope` flag to control where the configuration is saved:

| Scope | Flag | Effect | |-------|------|--------| | Local (default) | `--scope local` | Available only to you in the current project | | Project | `--scope project` | Shared with the team via `.mcp.json` | | User | `--scope user` | Available to you across all projects |

The repository is also a Claude Code plugin (skill plus server): `/plugin marketplace add robertcoop/openscad-mcp` then `/plugin install openscad-mcp@openscad-mcp`.

Claude Desktop

Add to your configuration file:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

{
  "mcpServers": {
    "openscad": {
      "command": "uvx",
      "args": ["openscad-mcp"],
      "env": {
        "OPENSCAD_PATH": "/usr/bin/openscad"
      }
    }
  }
}

Then restart Claude Desktop.

Cursor / Windsurf / VS Code

Add a `.mcp.json` file to your project root:

{
  "mcpServers": {
    "openscad": {
      "command": "uvx",
      "args": ["openscad-mcp"]
    }
  }
}

Manual / Standalone

# From PyPI (no install required)
uvx openscad-mcp

# The development version, straight from GitHub
uvx --from git+https://github.com/robertcoop/openscad-mcp.git openscad-mcp

# Or clone and run locally
git clone https://github.com/robertcoop/openscad-mcp.git
cd openscad-mcp
uv run openscad-mcp

# Run an assembly check file from a shell or a Makefile (exit code 0/1/2)
uvx openscad-mcp check checks.yaml --allow /path/to/project

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.

.claude-plugin/marketplace.json · Manifest · 15 lines

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

  1. {
  2. "name": "openscad-mcp",
  3. "owner": {
  4. "name": "Coop",
  5. "url": "https://github.com/robertcoop"
  6. },
  7. "description": "OpenSCAD tooling for AI assistants: rendering, measurement, validation, and export, plus a design skill for 3D-printable parts.",
  8. "plugins": [
  9. {
  10. "name": "openscad-mcp",
  11. "source": "./",
  12. "description": "OpenSCAD rendering, measurement, validation, and export as MCP tools, plus the openscad-design skill."
  13. }
  14. ]
  15. }
README.md · README · 509 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. [![PyPI](https://img.shields.io/pypi/v/openscad-mcp)](https://pypi.org/project/openscad-mcp/)
  3. [![CI](https://github.com/robertcoop/openscad-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/robertcoop/openscad-mcp/actions/workflows/ci.yml)
  4. [![Python](https://img.shields.io/pypi/pyversions/openscad-mcp)](https://pypi.org/project/openscad-mcp/)
  5. [![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)
  6. [![License](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
  7. A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that lets AI
  8. assistants design 3D-printable parts and assemblies in [OpenSCAD](https://openscad.org):
  9. render with a stated scale, measure exact geometry, check assemblies for interference
  10. and clearance, extract holes and features, judge printability, and export. Built with
  11. [FastMCP](https://gofastmcp.com) for Python; OpenSCAD 2021.01 is the supported floor
  12. and dev snapshots are used when present.
  13. ## Prerequisites
  14. - **[OpenSCAD](https://openscad.org/downloads.html)** installed on your system
  15. - **[uv](https://docs.astral.sh/uv/getting-started/installation/)** (recommended) or Python 3.10+
  16. ## Installation
  17. The server is published on PyPI as `openscad-mcp`, so [uv](https://docs.astral.sh/uv/)
  18. runs it with no clone and no virtualenv: `uvx openscad-mcp`. uv keeps a cached
  19. copy; `uv tool upgrade openscad-mcp` (or `uvx openscad-mcp@latest`) pulls a
  20. new release, and `uvx openscad-mcp@0.6.1` pins one.
  21. ### Claude Code
  22. Add the server with a single command:
  23. ```bash
  24. claude mcp add openscad --transport stdio -- uvx openscad-mcp
  25. ```
  26. Or, if OpenSCAD is not on your PATH:
  27. ```bash
  28. claude mcp add openscad --transport stdio \
  29. --env OPENSCAD_PATH=/path/to/openscad -- uvx openscad-mcp
  30. ```
  31. Use the `--scope` flag to control where the configuration is saved:
  32. | Scope | Flag | Effect |
  33. |-------|------|--------|
  34. | Local (default) | `--scope local` | Available only to you in the current project |
  35. | Project | `--scope project` | Shared with the team via `.mcp.json` |
  36. | User | `--scope user` | Available to you across all projects |
  37. The repository is also a Claude Code plugin (skill plus server):
  38. `/plugin marketplace add robertcoop/openscad-mcp` then
  39. `/plugin install openscad-mcp@openscad-mcp`.
  40. ### Claude Desktop
  41. Add to your configuration file:
  42. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  43. - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  44. ```json
  45. {
  46. "mcpServers": {
  47. "openscad": {
  48. "command": "uvx",
  49. "args": ["openscad-mcp"],
  50. "env": {
  51. "OPENSCAD_PATH": "/usr/bin/openscad"
  52. }
  53. }
  54. }
  55. }
  56. ```
  57. Then restart Claude Desktop.
  58. ### Cursor / Windsurf / VS Code
  59. Add a `.mcp.json` file to your project root:
  60. ```json
  61. {
  62. "mcpServers": {
  63. "openscad": {
  64. "command": "uvx",
  65. "args": ["openscad-mcp"]
  66. }
  67. }
  68. }
  69. ```
  70. ### Manual / Standalone
  71. ```bash
  72. # From PyPI (no install required)
  73. uvx openscad-mcp
  74. # The development version, straight from GitHub
  75. uvx --from git+https://github.com/robertcoop/openscad-mcp.git openscad-mcp
  76. # Or clone and run locally
  77. git clone https://github.com/robertcoop/openscad-mcp.git
  78. cd openscad-mcp
  79. uv run openscad-mcp
  80. # Run an assembly check file from a shell or a Makefile (exit code 0/1/2)
  81. uvx openscad-mcp check checks.yaml --allow /path/to/project
  82. ```
  83. ## Available Tools
  84. Every tool response carries `errors`, `warnings` and `hints` parsed from
  85. OpenSCAD's output. Check them: OpenSCAD exits 0 on a failed `assert()` or an
  86. unknown module and draws a blank scene.
  87. ### Rendering
  88. | Tool | Description |
  89. |------|-------------|
  90. | `render` | Images with a text digest before each one (camera, view direction, scale, bbox). `mode=views` (one image per view, or a custom camera), `mode=section` (exact cross-section with a scale bar), `mode=parts` (each part in its own colour, `isolate` ghosts the rest), `mode=compare` (before/after). `grounded=true` gives an orthographic view with a stated mm/px scale; `annotate=true` adds a scale bar, axis triad and bbox dimensions |
  91. ### Assemblies
  92. | Tool | Description |
  93. |------|-------------|
  94. | `check` | Relations between named parts, exported separately and never unioned: `mode=interference` (clear / contact / interference with penetration depth and a witness point), `clearance` (exact minimum distance with closest points), `contact` (area, normal, plane; `kind=static|sliding`), `alignment` (coaxial hole stacks across parts, misalignment, orphans), `motion` (rigid sweeps with a full-turn certificate), `rules` (run a versioned YAML/JSON check file; exit code 0/1/2). Every row carries the tessellation `$fn`, and distances inside its error bound are reported as unresolved rather than as numbers |
  95. Parts are given inline as `parts=[{name, code, place?, frame?, ghost?, mass_g?, motion?}]` or in a check file (`frames`, `quality`, `parts`, `checks`, `model`). Any number in a rule may be a SCAD expression string (`point: "[BOLT_R, 0, BASE_H]"`) evaluated in the model's scope, so checks follow the parameters rather than a copy of them. `openscad-mcp check <file.yaml>` runs a check file from the shell with a meaningful exit code, so `make check` is one call.
  96. ### Export & Model Management
  97. | Tool | Description |
  98. |------|-------------|
  99. | `export_model` | Export to STL, 3MF, AMF, OFF, NEF3, DXF, SVG, PDF or CSG. With `parts=[...]` every part is exported in its assembly position and bundled into one 3MF with named objects (or a directory of STLs) |
  100. | `model` | `action=create|get|update|list|delete` for `.scad` files in a workspace, with content-hash etags. `template="part:<id>"` writes a purchased-part module from the catalog |
  101. ### Measurement & Validation
  102. | Tool | Description |
  103. |------|-------------|
  104. | `measure` | Exact numbers from the geometry: `model` (bbox, volume, area, components, watertight, `mesh_health`), `parts`, `section` (contours; the offset may be an expression in the model's scope), `mass` (grams; with `parts=` and `about_axis=` the assembly mass, centre of mass and inertia about an axis, with `mass_g` overrides for purchased parts), `probe` (solid/air and which part at points; ray crossings; line of sight along a polyline), `features` (holes from the CSG tree: axis, diameter, depth, through/blind, undersize at `$fn`, fit names), `printability` (overhang patches with unsupported reach, thickness distribution vs nozzle, islands, support estimate; facts only), `orientation` (candidate orientations, no winner chosen), `anchors` (BOSL2 anchor frames in the assembly frame). Accepts an existing STL/SVG via `mesh` |
  105. | `validate` | `mode=syntax`, `geometry`, `predicates` (with `sweep={variable, values}` reporting the crossing), `includes` (references resolved or not, plus the BOSL2 lint: a module from a `use`d file placed by `attach()` is silently put at CENTER; `autofix=true` applies the rewrite when it is safe), `printability` (rules from the design-rule reference over measured facts) |
  106. | `scad_eval` | Evaluate expressions in a model's variable scope and get typed values (number, vector, string, bool, range, undef) |
  107. | `reference` | Sourced engineering data with confidence labels: fits (also bidirectional: `diameter_mm=3.3` names the hole, `shaft_mm`+`bore_mm` names the fit), metric fasteners, heat-set inserts, bearings, magnets, joints, a purchased-parts catalog with BOSL2 modules and clearance masks, FDM design rules, materials, OpenSCAD cheatsheet, conventions |
  108. | `get_libraries` | Discover installed OpenSCAD libraries |
  109. | `check_openscad` | Verify OpenSCAD installation, version and capabilities |
  110. ### Project Support
  111. | Tool | Description |
  112. |------|-------------|
  113. | `get_project_files` | List `.scad` files and their references; `mode=trace` follows a constant through the project (what depends on it, what it depends on) |
  114. | `clear_cache` | Clear the render cache |
  115. ## Usage Examples
  116. Once connected, ask your AI assistant:
  117. - *"Render a cube with rounded edges"*
  118. - *"Show me the front and top of this model with a scale bar"*
  119. - *"What is the volume and are there any cavities?"*
  120. - *"Cut a section through the lid at z = 12 and tell me the wall thickness"*
  121. - *"Colour the body and lid differently and ghost the body"*
  122. - *"What clearance should I use for an M3 screw and a press-fit 608 bearing?"*
  123. - *"Compare the model before and after changing the radius to 15"*
  124. - *"Export my gear model to STL"*
  125. The server also publishes MCP resources (`openscad://conventions`,
  126. `openscad://cheatsheet`, `openscad://reference/{topic}`) and server
  127. instructions with the coordinate and assembly conventions it expects. A
  128. Claude Code skill lives in `skills/openscad-design/SKILL.md` and the repo can
  129. be installed as a Claude Code plugin (`.claude-plugin/`).
  130. ### Tool Parameters
  131. [API.md](./API.md) documents every tool and every parameter. Four parameters
  132. account for most of the questions:
  133. - **`parts`** — a list of `{"name": ..., "code": ..., "place": ...}` objects,
  134. accepted by `render(mode="parts")`, `measure(mode="parts")`, `check` and
  135. `export_model`. `code` is the statement that instantiates the part
  136. (`lid();`) and `place` is an optional OpenSCAD transform wrapped around it
  137. (`translate([0,0,20])`). Each part is exported on its own, so its identity
  138. survives; an assembly is never unioned. `measure(mode="parts")` measures each
  139. part in its placed position (the response says `frame: "assembly"`), the
  140. same grammar `check`, `render` and `export_model` use.
  141. - **`quality`** — `draft`, `normal`, `high`, or an integer `$fn`. It sets
  142. `$fn`/`$fa`/`$fs` for the run. It is a correctness knob, not only a speed
  143. one: `check` reports a distance smaller than the tessellation error bound as
  144. `UNRESOLVED` rather than guessing, and the fix is a higher quality.
  145. - **`variables`** — a dict injected as OpenSCAD variables. In the wrapped modes
  146. (section, parts, `scad_eval`) they are appended to the wrapped module body
  147. rather than passed with `-D`, and they are injected at file scope as well, so
  148. a constant derived inside an included file still sees them. This is how you
  149. set a `$preview` guard variable for an export.
  150. - **`include_paths`** — extra directories added to `OPENSCADPATH`. When
  151. `MCP_ALLOWED_PATHS` is set, every entry is validated against it, as is every
  152. file OpenSCAD actually reads.
  153. Exactly one of `scad_content` or `scad_file` is required by every tool that
  154. takes source. All parameter parsers accept multiple input formats (JSON
  155. strings, lists, dicts, CSV) for AI assistant compatibility.
  156. Each image costs roughly 640 vision tokens at 800x600, and image sizes are
  157. clamped to 1568 px on the long edge, above which vision models downscale
  158. anyway. Ask for the views that answer a question rather than all of them.
  159. Auto-fit renders (`grounded=false`) have no recoverable absolute scale, which
  160. the digest states.
  161. ## Configuration
  162. ### Environment Variables
  163. | Variable | Description | Default |
  164. |----------|-------------|---------|
  165. | `OPENSCAD_PATH` | Path to OpenSCAD executable | Auto-detected |
  166. | `MCP_TEMP_DIR` | Temporary file directory | `/tmp/openscad-mcp` |
  167. | `MCP_TRANSPORT` | Transport type: `stdio`, `http`, `sse` | `stdio` |
  168. | `MCP_HOST` | Host for HTTP/SSE transport | `localhost` |
  169. | `MCP_PORT` | Port for HTTP/SSE transport | `8000` |
  170. | `MCP_MAX_CONCURRENT_RENDERS` | Max parallel renders | `5` |
  171. | `MCP_RENDER_TIMEOUT` | Render timeout in seconds | `300` |
  172. | `MCP_CACHE_ENABLED` | Enable render caching | `true` |
  173. | `MCP_CACHE_SIZE_MB` | Max cache size in MB | `500` |
  174. | `MCP_CACHE_TTL_HOURS` | Cache TTL in hours | `24` |
  175. | `MCP_LOG_LEVEL` | Logging level | `INFO` |
  176. | `MCP_MAX_FILE_SIZE_MB` | Max SCAD file size | `10` |
  177. | `MCP_ALLOWED_PATHS` | Directories scripts may read from (`os.pathsep`-separated) | unset = no validation |
  178. | `MCP_MAX_MEMORY_MB` | Address-space limit per OpenSCAD process (POSIX), `0` disables | `4096` |
  179. | `MCP_MAX_IMAGE_WIDTH` / `MCP_MAX_IMAGE_HEIGHT` | Render size clamp (aspect preserved) | `1568` |
  180. | `MCP_HARD_WARNINGS` | Pass `--hardwarnings` to OpenSCAD (see Security) | `false` |
  181. ### YAML Configuration
  182. Create a `config.yaml` for advanced configuration:
  183. ```yaml
  184. server:
  185. name: "OpenSCAD MCP Server"
  186. version: "0.1.0"
  187. transport: stdio
  188. rendering:
  189. max_concurrent: 5
  190. timeout_seconds: 300
  191. default_color_scheme: Cornfield
  192. cache:
  193. enabled: true
  194. max_size_mb: 500
  195. ttl_hours: 24
  196. security:
  197. rate_limit: 60
  198. max_file_size_mb: 10
  199. allowed_paths: # null = no path validation at all (a warning is logged)
  200. - /home/me/projects/parts
  201. max_memory_mb: 4096
  202. ```
  203. ## Security
  204. ### Threat model
  205. The server runs OpenSCAD on source it is handed. OpenSCAD can read any file
  206. the process can read, through `include <>`, `use <>`, `import()` and
  207. `surface()`, and can return what it read as echo output or as geometry. The
  208. guarantees below hold **only when `allowed_paths` is configured**. Out of the
  209. box it is unset, no path validation is performed, and the server logs a
  210. warning at startup saying so.
  211. What is enforced:
  212. - **Path validation on arguments**: `scad_file`, `include_paths` (in every
  213. tool) and export `output_path` must lie inside `allowed_paths`. Containment
  214. uses resolved paths, so symlinks and `..` cannot escape.
  215. - **Path validation on the dependency closure**: every file OpenSCAD actually
  216. read is recorded with `-d` and checked after the run. If any lies outside
  217. `allowed_paths`, the standard library directories, or the server temp dir,
  218. the output (image, mesh, echo text) is withheld and the call fails. This
  219. closes the `include <...>`-as-data and `surface(file=...)` channels.
  220. - **Memory ceiling**: each OpenSCAD process runs under `RLIMIT_AS`
  221. (`max_memory_mb`, default 4 GB) on POSIX hosts. OpenSCAD has no ceiling of
  222. its own; a small `minkowski()` can otherwise consume all host memory.
  223. - **Timeout**: `timeout_seconds`, default 300 s; partial stderr is kept.
  224. - **Echo channel bounds**: `echo_output` is capped (200 lines, 2000 chars
  225. per line) and labelled as untrusted content from the rendered file.
  226. - **File size limits**, **variable name validation**
  227. (`^\$?[a-zA-Z_][a-zA-Z0-9_]*$`) and **model name validation** (no path
  228. traversal) as before.
  229. What is not enforced: no OS-level sandbox (no network isolation, no
  230. filesystem namespace). For untrusted input run the server inside a
  231. container or under Landlock/bubblewrap with only the project directory
  232. mounted.
  233. ### Why `--hardwarnings` is off
  234. `--hardwarnings` stops OpenSCAD at the first warning but still exits 0, so
  235. it produced blank renders and silently truncated `echo_output` with no
  236. indication. Warnings now reach the assistant through the structured
  237. `warnings`, `errors` and `hints` fields on every tool response instead.
  238. Set `MCP_HARD_WARNINGS=true` to restore the flag.
  239. ## Development
  240. ```bash
  241. # Clone the repo
  242. git clone https://github.com/robertcoop/openscad-mcp.git
  243. cd openscad-mcp
  244. # Install dependencies (the dev extra; there is no dependency-groups table,
  245. # so `uv sync --dev` would remove pytest, ruff, black and mypy)
  246. uv sync --extra dev
  247. # Run the server
  248. uv run openscad-mcp
  249. # Run the assembly checker on a check file
  250. uv run openscad-mcp check examples/checks/turntable.yaml
  251. # Run tests
  252. uv run pytest
  253. # Lint & format. The tree carries pre-existing findings, so expect noise;
  254. # CI gates only on `ruff check --select F,E9,B src/openscad_mcp/`.
  255. uv run ruff check src/ tests/
  256. uv run black --check src/ tests/
  257. # Type check (also not clean today)
  258. uv run mypy src/
  259. ```
  260. ### Project Structure
  261. ```
  262. openscad-mcp/
  263. ├── src/openscad_mcp/
  264. │ ├── server.py # FastMCP server, the 12 tools, rendering, cache, CLI
  265. │ ├── assembly.py # Part/Frame/Assembly model and the check-file grammar
  266. │ ├── checks.py # RuleEngine: the rules a check file can ask for
  267. │ ├── geom.py # Mesh kernel: BVH, tri-tri distance, winding number, sweeps
  268. │ ├── csgfeatures.py # CSG-dump parser: holes, bosses, cross-part alignment
  269. │ ├── massprops.py # Mass, centre of mass, inertia by tetrahedra
  270. │ ├── printability.py # Overhangs, wall thickness, islands, orientation candidates
  271. │ ├── analysis.py # Static analysis: BOSL2 $var shadowing lint, constant tracing
  272. │ ├── parts_catalog.py # Purchased-parts catalog loader and self-check
  273. │ ├── parts/*.scad # One generated BOSL2 file per catalogued part
  274. │ ├── threemf.py # Multi-object 3MF writer
  275. │ ├── wrappers.py # Source-level wrappers: include hoisting, variable injection
  276. │ ├── diagnostics.py # stderr -> Diagnostics; -d deps parsing; repair hints
  277. │ ├── camera.py # Orthographic camera model, fit, annotation, spatial digest
  278. │ ├── mesh.py # Stdlib STL/SVG analysis: welding, components, volumes
  279. │ ├── reference.py # Sourced engineering data: fits, fasteners, inserts, DFM
  280. │ ├── types.py # Pydantic models and enums
  281. │ └── utils/config.py # Configuration with env/YAML/dotenv support
  282. ├── tests/ # ~1,500 tests; 80% coverage floor
  283. ├── evals/ # Deterministic geometry eval harness, 15 tasks
  284. ├── examples/checks/ # A worked check file and its model
  285. ├── skills/openscad-design/ # Claude Code skill: the design loop
  286. └── .claude-plugin/ # Claude Code plugin manifest
  287. ```
  288. ### Testing
  289. ```bash
  290. # Run all tests with coverage (about 1,500 tests, roughly a minute)
  291. uv run pytest
  292. # Run specific markers: unit, config, integration, slow, performance, edge, render
  293. uv run pytest -m unit
  294. uv run pytest -m performance
  295. uv run pytest -m "not slow"
  296. # Run a single file, without the coverage gate
  297. uv run pytest tests/test_helpers.py -v --no-cov
  298. ```
  299. Most tests mock the OpenSCAD subprocess, so no OpenSCAD installation is needed
  300. to run the suite. A mock that stands in for a render has to write both output
  301. files OpenSCAD would have written: the `-o` target and the `-d` dependency file
  302. that the cache manifest is built from. Tests that do need the real binary skip
  303. themselves when it is absent.
  304. CI runs the suite on Python 3.10 and 3.12 with OpenSCAD 2021.01 and BOSL2
  305. installed, under `xvfb-run` because PNG export on 2021.01 needs a display. It
  306. also builds the wheel, installs it in a clean environment, and asserts that a
  307. client sees exactly 12 tools. Coverage floor: 80%.
  308. ## Troubleshooting
  309. ### OpenSCAD Not Found
  310. ```bash
  311. # Check if OpenSCAD is installed
  312. which openscad # Linux/macOS
  313. where openscad.exe # Windows
  314. # Set the path explicitly
  315. export OPENSCAD_PATH=/path/to/openscad
  316. ```
  317. ### Server Not Connecting
  318. ```bash
  319. # Verify the server starts correctly
  320. uvx openscad-mcp
  321. # In Claude Code, check MCP status
  322. /mcp
  323. ```
  324. ### Render Timeout
  325. Increase the timeout:
  326. ```bash
  327. export MCP_RENDER_TIMEOUT=600
  328. ```
  329. ### "Path not allowed" / "outside the allowed paths"
  330. `MCP_ALLOWED_PATHS` is set and the file is not under one of its roots. The
  331. check covers arguments and, separately, every file OpenSCAD actually opened, so
  332. a model that lives inside an allowed root but does `include <../shared/lib.scad>`
  333. outside it is refused and the output is withheld. Add both roots:
  334. ```bash
  335. export MCP_ALLOWED_PATHS="$HOME/cad:$HOME/cad-shared"
  336. ```
  337. Leaving the variable unset disables path validation entirely, which the server
  338. logs a warning about at startup. See [Threat model](#threat-model).
  339. ### An export or a measurement comes back empty
  340. The usual cause is a `$preview` guard: a file that instantiates its geometry
  341. only inside `if ($preview)` renders in the GUI and exports nothing, because
  342. `$preview` is false for a render to a file. Pass the guard variable explicitly:
  343. ```
  344. measure(scad_file="part.scad", variables={"$preview": true})
  345. ```
  346. A `difference()` whose first child is smaller than what follows also yields
  347. nothing. `validate(mode="syntax")` will not catch either one; the exit code is
  348. 0 in both cases.
  349. ### `check` rows say `UNRESOLVED`
  350. The distance in question is smaller than the tessellation error of the mesh, so
  351. the answer would be an artefact of `$fn` rather than of the design. Re-run with
  352. `quality="high"` or an explicit integer `$fn`. Every row reports the `quality.fn`
  353. it was computed at.
  354. ### A result looks stale
  355. Renders are cached under `~/.cache/openscad-mcp/`, keyed on every render
  356. parameter plus a manifest of every file OpenSCAD read. Editing an included file
  357. normally invalidates the entry, but if a response says `cached: true` and the
  358. number disagrees with the source, clear it:
  359. ```
  360. clear_cache()
  361. ```
  362. ### Renders fail on a headless machine
  363. OpenSCAD 2021.01 needs a display to export PNG even in headless mode. Run the
  364. server under a virtual framebuffer:
  365. ```bash
  366. xvfb-run -a uv run openscad-mcp
  367. ```
  368. Exports, measurements and checks produce meshes rather than images and do not
  369. need a display.
  370. ## Contributing
  371. 1. Fork the repository
  372. 2. Create a feature branch (`git checkout -b feature/my-feature`)
  373. 3. Make your changes with tests
  374. 4. Ensure tests pass (`uv run pytest`)
  375. 5. Open a Pull Request
  376. Commit style: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
  377. [CONTRIBUTING.md](./CONTRIBUTING.md) covers the module map, how the tests mock
  378. OpenSCAD, the design rules that should not be undone, and how to add a
  379. parts-catalog entry or a check rule.
  380. ## License
  381. MIT — see [LICENSE](./LICENSE)
  382. ## Acknowledgments
  383. - [OpenSCAD](https://openscad.org) — Programmable CAD software. Everything here
  384. is a wrapper around its CLI.
  385. - [FastMCP](https://gofastmcp.com) — Python MCP framework
  386. - [Model Context Protocol](https://modelcontextprotocol.io) — The MCP specification
  387. - [BOSL2](https://github.com/BelfrySCAD/BOSL2) — Used, not vendored, by the
  388. purchased-parts catalog and by the BOSL2 anchor probe. BSD-2-Clause; install
  389. it separately.
  390. - Dimensional data in `reference` and `parts` is cited entry by entry, with a
  391. confidence label on every number. See
  392. [src/openscad_mcp/parts/README.md](./src/openscad_mcp/parts/README.md).

Ratings and comments

Sign in to rate this skill.

Sign in

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