OpenSCAD MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@OpenSCAD MCP Server render a cube with a sphere next to it and save as /tmp/shapes.png"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
OpenSCAD MCP Server
A Model Context Protocol (MCP) server that provides OpenSCAD rendering capabilities. This server allows you to render OpenSCAD code to PNG images through a standardized MCP interface.
Features
Headless OpenSCAD Rendering: Execute OpenSCAD code and generate PNG images without a GUI
Flexible Camera Control: Support for custom camera positioning and orientation
Cross-Platform: Configurable OpenSCAD binary path for different operating systems
Related MCP server: OpenSCAD MCP Server
Prerequisites
Node.js: Version 18 or higher
OpenSCAD: Nightly (dev) version must be installed on your system. Download and install from OpenSCAD.org.
Installation
Clone this repository:
git clone https://github.com/rahulgarg123/openscad-mcp.git cd openscad-mcpInstall dependencies:
npm installBuild the project:
npm run build
Configuration
OpenSCAD Binary Path
By default, the server looks for OpenSCAD at /Applications/OpenSCAD.app/Contents/MacOS/OpenSCAD (macOS path). You can customize this by setting the OPENSCAD_BINARY environment variable.
Usage as MCP Server in Gemini-cli
In your gemini settings.json file, e.g., ~/.gemini/settings.json, add the following:
"mcpServers": {
"openscad": {
"command": "node",
"args": ["/path/to/openscad-mcp/dist/index.js"],
"env": {
"OPENSCAD_BINARY": "/path/to/OpenSCAD/binary"
}
}
}Use included GEMINI.md file in the folder you want to generate openSCAD code in.
Available Tools
render_openscad
Renders OpenSCAD code to a PNG image file.
Parameters:
code(string, required): The OpenSCAD code to renderoutput_path(string, required): Path where the rendered PNG image should be savedcamera(string, optional): Camera parameters in one of these formats:translate_x,y,z,rot_x,y,z,dist- Translation, rotation, and distanceeye_x,y,z,center_x,y,z- Eye position and center point
Example Request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "render_openscad",
"arguments": {
"code": "cube([20, 30, 10]); translate([25, 0, 0]) sphere(r=8);",
"output_path": "/tmp/my_render.png",
"camera": "0,0,0,60,0,315,100"
}
}
}Response:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "OpenSCAD rendering completed successfully\n\nOutput:\n...\n\nRendered image saved to: /tmp/my_render.png"
}
]
}
}Examples with gemini-cli
Prompt:
Generate openscad code for a very beautiful and unique planter. Iterate as many times as possible on the design, looking at the rendering in each iteration and improving it. The goal is to generate a unique and aesthetic planter design amenable for 3D printing.
|
First Iteration |
|
Final Iteration |
Generated OpenSCAD code:
module unique_planter(
height = 100,
width = 50,
wall_thickness = 4,
twist = 90,
freq = 8,
amp = 2,
drainage_hole_rad = 5
) {
$fn=100;
difference() {
linear_extrude(height = height, scale = 1.2, twist = twist, slices = 200) {
polygon([
for (a = [0:360/$fn:359])
let (r = width/2 + amp*sin(a*freq) + amp*sin(a*freq/2))
[r*cos(a), r*sin(a)]
]);
}
translate([0,0,wall_thickness]) {
linear_extrude(height = height, scale = 1.2, twist = twist, slices = 200) {
polygon([
for (a = [0:360/$fn:359])
let (r = width/2 - wall_thickness + amp*sin(a*freq) + amp*sin(a*freq/2))
[r*cos(a), r*sin(a)]
]);
}
}
translate([0,0,-1]) {
cylinder(h = wall_thickness+2, r = drainage_hole_rad);
}
}
}
unique_planter();Testing
Run the included tests to verify everything works:
node test_client.jsDevelopment
Scripts
npm run build: Compile TypeScript to JavaScriptnpm run start: Start the MCP servernpm run dev: Watch mode for development
Project Structure
openscad-mcp/
├── src/
│ └── index.ts # Main MCP server implementation
├── dist/ # Compiled JavaScript output
├── test_client.js # Basic test client
├── test.scad # Sample OpenSCAD file
├── package.json # Node.js dependencies and scripts
├── tsconfig.json # TypeScript configuration
└── README.md # This fileTroubleshooting
OpenSCAD Not Found
Error: spawn /Applications/OpenSCAD.app/Contents/MacOS/OpenSCAD ENOENTSolution: Verify OpenSCAD is installed and set the correct OPENSCAD_BINARY path.
Permission Denied
Error: EACCES: permission denied, open '/path/to/output.png'Solution: Ensure the output directory exists and is writable.
Rendering Timeout
Error: Command failed: timeoutSolution: Simplify your OpenSCAD code or increase the timeout in the source code.
Contributing
Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Submit a pull request
Links
Available Tools
1 toolrender_openscadC
Render OpenSCAD code to PNG using OpenSCAD in headless mode
Inputs: code (required), output_path (required), camera.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
With only one tool, there is no possibility of ambiguity or overlap between tools. The single tool 'render_openscad' has a clear and distinct purpose, making it impossible for an agent to misselect between tools.
A single tool inherently has perfect naming consistency, as there are no other tools to compare it against. The tool name 'render_openscad' follows a clear verb_noun pattern, but consistency cannot be assessed across multiple tools in this case.
A single tool is generally too few for most server purposes, as it limits functionality and may indicate an incomplete or overly narrow scope. While it might be appropriate for a very specific task, it feels thin and could hinder agent workflows that require more operations.
The server appears to target OpenSCAD rendering, but with only a render tool, there are significant gaps. For example, there are no tools for creating, editing, or managing OpenSCAD code, which are core operations in this domain. This severely limits the surface and will likely cause agent failures.
Maintenance
Related MCP Connectors
Parametric 3D CAD for AI agents: build print-ready parts, check them, export STL, 3MF or STEP.
Headless CAD engine & MCP server for 2D/3D drafting, solids, DXF/SVG export, and automation.
A browser 3D CAD for your AI: it scripts real-size models, uCAD builds them and returns pictures.
Text-to-CAD: build exact STEP or 3MF/STL on the server, each stated requirement measured.
Related MCP Servers
- AlicenseAqualityAmaintenanceEnables AI assistants to render 3D models from OpenSCAD code, generating single views or multiple perspectives with full camera control. Supports animations, custom parameters, and returns base64-encoded PNG images for seamless integration.12516 PyPI173MIT
- AlicenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to render 3D models by providing tools to execute OpenSCAD code and generate single or multi-perspective views. It returns high-quality PNG renderings directly to LLM applications for visual feedback and 3D model visualization.MIT
- AlicenseNot gradedqualityDmaintenanceEnables editing of STL 3D model files through the Model Context Protocol, providing tools for reading, writing, transforming, and creating primitive shapes.MIT
- AlicenseNot gradedqualityDmaintenanceEnables agents to validate, render preview (PNG), and export OpenSCAD models to various formats using the openscad CLI.ISC

