MCP Server for OpenSCAD
Loading README and project media…
OpenSCAD MCP Server exposes the OpenSCAD CLI as Model Context Protocol (MCP) tools so MCP-compatible clients (including LLM-based clients) can validate, render, and export parametric 3D models using OpenSCAD.
This repo targets a v1.0 tool surface: stable, minimal, deterministic, and local-first (stdio transport only).
All tool details (args, options, response payloads) are documented in docs/TOOLING.md.
Core:
ping: server + OpenSCAD discovery metadatalist_formats: supported export/preview formatsvalidate_scad: compile validation + parsed diagnosticsexport_model: export stl/3mf/offrender_preview: export pngrender_scad: export model + preview in one callbatch_render_scad: run multiple parameter variants sequentiallyTemplates & modules:
list_templates / render_template: built-in parametric templates shipped with the serverlist_modules / render_module: render from a simple module registry (OPENSCAD_MCP_MODULE_ROOT)Artifact ergonomics (opt-in, per call via options):
inline_artifact_bytes: return base64 bytes in responses (size-limited)introspect_artifacts: basic artifact metadata inspection (size-limited)use_cache: content-addressed cache (requires OPENSCAD_MCP_CACHE_ROOT)Prerequisites:
openscad available on your PATH (or set OPENSCAD_MCP_OPENSCAD_PATH)Install (editable, recommended via venv):
python -m venv .venv
. .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev]"
Run the MCP server (stdio):
openscad-mcp
Example tool call arguments (conceptual JSON payload):
{
"tool": "render_scad",
"args": {
"scad_source": "cube([w,h,d]);",
"params": {
"w": 10,
"h": 20,
"d": 5
},
"options": {
"format": "stl",
"imgsize": [
512,
512
],
"inline_artifact_bytes": true
}
}
}
Artifacts are produced in a per-request build directory:
OPENSCAD_MCP_KEEP_ARTIFACTS=true (and optionally
OPENSCAD_MCP_ARTIFACT_ROOT) so returned artifact.path values remain valid after the tool returns.inline_artifact_bytes=true (subject to
OPENSCAD_MCP_MAX_INLINE_BYTES).
inline_artifact_bytes=true also results in an image attachment for render_preview /
render_scad responses.When OPENSCAD_MCP_ARTIFACT_ROOT is set, each request writes to a unique subdirectory (for example:
./artifacts/<uuid>/preview.png).
Run tests:
pytest -q
pytest -q -m "not integration"
Run integration tests inside the Docker image (real OpenSCAD):
./scripts/pytest-integration-docker
This server uses MCP stdio transport (no network listener). To run it in Docker while still exposing a stdio MCP process to a host MCP client, use the provided wrapper which forwards stdin/stdout to a container.
Build the image and create a host-visible artifacts directory:
mkdir -p artifacts
docker compose build
Run the MCP server via Docker (stdio passthrough):
./scripts/openscad-mcp-docker
Windows PowerShell:
.\scripts\openscad-mcp-docker.ps1
Artifacts are written inside the container under /artifacts and are volume-mounted to ./artifacts on the host.
If you need to enforce output size limits, set OPENSCAD_MCP_MAX_OUTPUT_BYTES.
Note: the container entrypoint uses an openscad-headless wrapper that prefers xvfb-run for PNG rendering, but
falls back to QT_QPA_PLATFORM (default minimal) if xvfb-run/xauth are unavailable.
Set the working directory to the project root folder.
{
"mcpServers": {
"openscad": {
"command": "powershell.exe",
"args": [
"-NoProfile",
"-ExecutionPolicy",
"Bypass",
"-File",
".\\scripts\\openscad-mcp-docker.ps1"
]
}
}
}
Model generation + validation:

Preview rendering + model export:

If OPENSCAD_MCP_MODULE_ROOT is set, it must contain an index.json manifest plus *.scad files:
{
"modules": [
{
"id": "my_part",
"description": "Example module.",
"entry": "my_part"
}
]
}
The server will load my_part.scad and call my_part() (or entry if it already includes parentheses).
Environment variables:
OPENSCAD_MCP_LOG_LEVEL: log level (default INFO)OPENSCAD_MCP_OPENSCAD_PATH: optional path to openscad (overrides PATH discovery)OPENSCAD_MCP_QT_QPA_PLATFORM: Qt platform plugin for headless fallback (default minimal)OPENSCAD_MCP_TIMEOUT_S: OpenSCAD subprocess timeout in seconds (default 30)OPENSCAD_MCP_ARTIFACT_ROOT: optional root directory for per-request build dirsOPENSCAD_MCP_KEEP_ARTIFACTS: if true, keep per-request build dirsOPENSCAD_MCP_MAX_OUTPUT_BYTES: fail if the generated artifact exceeds this sizeOPENSCAD_MCP_MAX_INLINE_BYTES: max bytes to inline when inline_artifact_bytes=true (default 5 MB)OPENSCAD_MCP_MAX_INTROSPECT_BYTES: max bytes to read for introspection (default 2 MB)OPENSCAD_MCP_CACHE_ROOT: root directory for artifact cache (enables use_cache=true)OPENSCAD_MCP_MODULE_ROOT: module registry root containing index.json + *.scad filesOPENSCAD_MCP_INCLUDE_ROOTS: comma-separated allowlist for use/include (best-effort enforcement)This server is designed to be local-first and run over stdio. Do not expose it directly to the internet.
OpenSCAD compilation should be treated as untrusted workload (CPU/memory heavy models, file use/include, etc). See
docs/SECURITY.md for the project security stance and recommendations.
docs/TOOLING.mddocs/SECURITY.mdexamples/README.mdCONTRIBUTING.mdCODE_OF_CONDUCT.mdSECURITY.mdCHANGELOG.mdThe v1.0 tool surface is implemented. Future enhancements are tracked via GitHub issues (e.g. more templates, deeper OpenSCAD diagnostics coverage, additional formats, optional session-like workflows).
MIT
Pretty much the whole project was generated With ChatGPT 5.1 using Codex CLI inside JetBrains PyCharm. The goal of this project is to investigate the implementation of MCP protocol in Python.