openscad

OpenSCAD Model Context Protocol server and browser UI. OpenSCAD runs in WebAssembly, so the service needs no native OpenSCAD installation.

Run

docker compose -f compose/docker-compose.yaml up -d

• Browser: http://127.0.0.1:3333/

• MCP: http://127.0.0.1:3333/mcp

• Workspace: ${WORKSPACE_PATH:-./workspace} from the Compose directory, mounted at /workspace

The Compose example pulls ghcr.io/miloszkolber/openscad:latest for linux/amd64. To use a local build instead:

docker build -f docker/openscad.Dockerfile -t openscad:local .
OPENSCAD_IMAGE=openscad:local docker compose -f compose/docker-compose.yaml up -d

MCP_AUTH_TOKEN protects /mcp. WORKSPACE_DIR, MAX_RENDER_MS, MAX_OUTPUT_MB, MAX_INPUT_MB and MAX_PARALLEL_JOBS are documented in compose/.env.example. The browser and model routes stay public; use a reverse proxy for private repositories.

Related MCP server: openscad-mcp

Tools

• openscad_validate: validate a workspace SCAD file or inline source.

• openscad_export_model: export to STL, 3MF, OFF, CSG, DXF or SVG.

• openscad_screenshot: return a shaded PNG or WebP image, optionally written to the workspace.

• openscad_analyze_model: compute the bounding box and triangle count.

• workspace_list_files, workspace_read_file, workspace_write_file, workspace_delete_file: manage workspace files.

All OpenSCAD tools accept path or scad. A workspace path stages sibling files for relative include and import statements. Client setup and raw JSON examples are in openspec/references/mcp-clients.md.

Build and release

The Build image workflow runs on pushes, pull requests, manual dispatch and every Monday at 04:00 Europe/Warsaw. It runs typecheck, lint, the full test suite and the build, then builds and smoke-tests one linux/amd64 image before publishing:

• ghcr.io/miloszkolber/openscad:latest

• ghcr.io/miloszkolber/openscad:sha-<commit>

Dependabot checks npm packages, Docker base images and GitHub Actions weekly. The runtime image uses Node 26 on a distroless base; TypeScript 7 performs typechecking while TypeScript 6 remains the ESLint and ts-loader API.

Development

npm ci
npm run prepare:assets
npm run build
npm test
npm run lint
npm run typecheck
npm run check:docs

mcp/ contains the MCP runtime, web/ the browser UI, docker/ the image recipe and compose/ the deployment example. The mock backend is available with OPENSCAD_BACKEND=mock npm run dev. The browser check accepts an already authorized CDP endpoint: APP_URL=http://127.0.0.1:3333 BROWSER_URL=http://127.0.0.1:9222 npm run test:browser.

Documentation

openspec/ is the single documentation and planning tree: implemented contracts, scoped changes and the deferred backlog.

Licensing

The MCP server is MIT licensed. The browser UI is derived from OpenSCAD Playground and is GPLv2 or later; its notices are in web/LICENSE.md. This repository builds on the MIT-licensed upstream project.