Content
# openscad-wasm-mcp
An OpenSCAD Model Context Protocol (MCP) server that runs OpenSCAD in Node.js/TypeScript using WebAssembly (`openscad-wasm`). No native OpenSCAD installation on the host is required.
## Quick Start
### 1. Run with Docker Compose
By default, the server runs in Docker with restricted privileges:
```bash
docker compose up --build
```
The MCP server listens on `http://127.0.0.1:3333/mcp`.
### 2. Configure MCP Client
Add the server to your MCP client configuration (e.g., `claude_desktop_config.json`):
**Using HTTP Transport (default):**
```json
{
"mcpServers": {
"openscad-wasm": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/client-cli", "http://127.0.0.1:3333/mcp"]
}
}
}
```
## Available Tools
### OpenSCAD Tools
- `openscad_validate`: Validates SCAD code and returns syntax/logical diagnostics.
- `openscad_export_model`: Exports model to `stl`, `3mf`, `off`, `csg`, `dxf`, or `svg`.
- `openscad_render_preview`: Generates a server-side WebP render or an interactive 3D preview link.
- `openscad_create_preview_link`: Generates a URL to open a browser-based interactive 3D viewer.
- `openscad_analyze_model`: Computes the model's bounding box and triangle count.
### Workspace Tools
- `workspace_list_files`: Lists files in the container workspace.
- `workspace_read_file`: Reads a file from the workspace.
- `workspace_write_file`: Writes a file to the workspace.
- `workspace_delete_file`: Deletes a file from the workspace.
## Artifacts
Renders and model exports are saved under `./workspace/artifacts` on the host. The MCP tool responses return metadata: `path`, `filename`, `format`, `mimeType`, `sizeBytes`, and `sha256`.
## Configuration
Customize runtime limits (memory, timeouts, directories) by copying `.env.example` to `.env` and editing the environment variables.
## Known Limitations
- **Performance**: Complex models can be slow or memory-intensive inside WebAssembly.
- **Visuals**: WebP previews do not preserve OpenSCAD colors, GUI helpers, or 2D camera perspectives.
- **Assets & Libraries**: Fonts and external libraries are not bundled; you must upload necessary files to the workspace first.
- **Format Support**: Build-specific limits may affect exports (e.g., `3mf` is currently unsupported).
## License
MIT License. See [LICENSE](LICENSE) for details. Dependencies (`openscad-wasm`, `sharp`) carry their own respective licenses.
