OpenSCAD MCP Server

Instructions

Implementation Reference

• src/openscad_mcp/server.py:638-768 (handler)

  Primary handler for the render_single MCP tool. Handles flexible parameter parsing, calls core renderer, manages output formats, and returns results.
  @mcp.tool async def render_single( scad_content: Optional[str] = None, scad_file: Optional[str] = None, view: Optional[str] = None, camera_position: Union[str, List[float], Dict[str, float], None] = None, camera_target: Union[str, List[float], Dict[str, float], None] = None, camera_up: Union[str, List[float], Dict[str, float], None] = None, image_size: Union[str, List[int], tuple, None] = None, color_scheme: str = "Cornfield", variables: Optional[Dict[str, Any]] = None, auto_center: bool = False, output_format: Optional[str] = "auto", ctx: Optional[Context] = None, ) -> Dict[str, Any]: """ Render a single view from OpenSCAD code or file. Args: scad_content: OpenSCAD code to render (mutually exclusive with scad_file) scad_file: Path to OpenSCAD file (mutually exclusive with scad_content) view: Predefined view name ("front", "back", "left", "right", "top", "bottom", "isometric", "dimetric") camera_position: Camera position - accepts [x,y,z] list, JSON string "[x,y,z]", or dict {"x":x,"y":y,"z":z} (default: [70, 70, 70]) camera_target: Camera look-at point - accepts [x,y,z] list, JSON string, or dict (default: [0, 0, 0]) camera_up: Camera up vector - accepts [x,y,z] list, JSON string, or dict (default: [0, 0, 1]) image_size: Image dimensions - accepts [width, height] list, JSON string "[width, height]", "widthxheight", or tuple (default: [800, 600]) color_scheme: OpenSCAD color scheme (default: "Cornfield") variables: Variables to pass to OpenSCAD auto_center: Auto-center the model output_format: Output format - "auto", "base64", "file_path", or "compressed" (default: "auto") ctx: MCP context for logging Returns: Dict with base64-encoded PNG image or file path """ if ctx: await ctx.info("Starting OpenSCAD render...") # Validate input if bool(scad_content) == bool(scad_file): raise ValueError("Exactly one of scad_content or scad_file must be provided") # If view keyword is provided, use preset camera settings if view: if view not in VIEW_PRESETS: raise ValueError(f"Invalid view name '{view}'. Must be one of: {', '.join(VIEW_PRESETS.keys())}") # Get preset camera settings preset_pos, preset_target, preset_up = VIEW_PRESETS[view] # Override camera parameters with preset values camera_position = list(preset_pos) camera_target = list(preset_target) camera_up = list(preset_up) # Auto-center is typically enabled for standard views if not auto_center: auto_center = True if ctx: await ctx.info(f"Using preset view '{view}' with camera position {camera_position}") else: # Parse camera parameters with proper defaults camera_position = parse_camera_param(camera_position, [70, 70, 70]) camera_target = parse_camera_param(camera_target, [0, 0, 0]) camera_up = parse_camera_param(camera_up, [0, 0, 1]) # Parse image size with flexible formats image_size = parse_image_size_param(image_size, [800, 600]) # Parse variables with flexible formats variables = parse_dict_param(variables, {}) try: # Run rendering (simplified synchronous version) # In production, this should use asyncio.run_in_executor image_data = await asyncio.get_event_loop().run_in_executor( None, render_scad_to_png, scad_content, scad_file, camera_position, camera_target, camera_up, image_size, color_scheme, variables, auto_center, ) if ctx: await ctx.info("Rendering completed successfully") # Apply response size management for single image if output_format and output_format != "base64": managed_result = manage_response_size( {"render": image_data}, output_format=output_format, max_size=20000, ctx=ctx ) # Check if we got extended format if isinstance(managed_result, dict) and "render" in managed_result: result_data = managed_result["render"] if isinstance(result_data, dict): # Extended format with metadata return { "success": True, **result_data, # Include type, data/path, mime_type "operation_id": str(uuid.uuid4()), "output_format": output_format if output_format != "auto" else "optimized" } # Default base64 response (backwards compatible) return { "success": True, "data": image_data, "mime_type": "image/png", "operation_id": str(uuid.uuid4()), } except Exception as e: if ctx: await ctx.error(f"Rendering failed: {str(e)}") return { "success": False, "error": str(e), "operation_id": str(uuid.uuid4()), }
• src/openscad_mcp/server.py:76-177 (helper)

  Core rendering helper that invokes OpenSCAD CLI to generate PNG image from SCAD input and returns base64-encoded data.
  def render_scad_to_png( scad_content: Optional[str] = None, scad_file: Optional[str] = None, camera_position: List[float] = [70, 70, 70], camera_target: List[float] = [0, 0, 0], camera_up: List[float] = [0, 0, 1], image_size: List[int] = [800, 600], color_scheme: str = "Cornfield", variables: Optional[Dict[str, Any]] = None, auto_center: bool = False, ) -> str: """ Render OpenSCAD code or file to PNG and return as base64. This is a simplified synchronous implementation for the MVP. """ openscad_cmd = find_openscad() if not openscad_cmd: raise RuntimeError("OpenSCAD not found. Please install OpenSCAD first.") config = get_config() # Ensure temp directory exists temp_dir_path = Path(config.temp_dir) temp_dir_path.mkdir(parents=True, exist_ok=True) # Create temporary files with tempfile.TemporaryDirectory(dir=config.temp_dir) as temp_dir: temp_path = Path(temp_dir) # Handle input source if scad_content: scad_path = temp_path / "input.scad" scad_path.write_text(scad_content) elif scad_file: scad_path = Path(scad_file) if not scad_path.exists(): raise FileNotFoundError(f"SCAD file not found: {scad_file}") else: raise ValueError("Either scad_content or scad_file must be provided") # Output path output_path = temp_path / "output.png" # Build OpenSCAD command cmd = [ openscad_cmd, "--hardwarnings", "-o", str(output_path), "--imgsize", f"{image_size[0]},{image_size[1]}", "--colorscheme", color_scheme, ] # Calculate camera distance import math dx = camera_position[0] - camera_target[0] dy = camera_position[1] - camera_target[1] dz = camera_position[2] - camera_target[2] distance = math.sqrt(dx*dx + dy*dy + dz*dz) # Add camera parameters camera_str = ( f"--camera=" f"{camera_position[0]},{camera_position[1]},{camera_position[2]}," f"{camera_target[0]},{camera_target[1]},{camera_target[2]}," f"{distance}" ) cmd.append(camera_str) if auto_center: cmd.append("--autocenter") cmd.append("--viewall") # Add variables if variables: for key, value in variables.items(): if isinstance(value, str): val_str = f'"{value}"' elif isinstance(value, bool): val_str = "true" if value else "false" else: val_str = str(value) cmd.extend(["-D", f"{key}={val_str}"]) # Add the SCAD file cmd.append(str(scad_path)) # Run OpenSCAD result = subprocess.run(cmd, capture_output=True, text=True, check=False) if result.returncode != 0: raise RuntimeError(f"OpenSCAD rendering failed: {result.stderr}") if not output_path.exists(): raise RuntimeError("OpenSCAD did not produce output file") # Read and encode the image with open(output_path, "rb") as f: image_data = f.read() # Return base64-encoded PNG return base64.b64encode(image_data).decode("utf-8")
• src/openscad_mcp/types.py:235-273 (schema)

  Pydantic model defining structured input parameters and validation for the render_single tool, including flexible parsing for camera positions and image sizes.
  class SingleRenderParams(RenderParams): """Parameters for single view rendering.""" view: Optional[Union[PredefinedView, str]] = Field( None, description="Predefined view name (front, back, left, right, top, bottom, isometric, dimetric) - overrides camera settings if provided" ) camera_position: Union[Vector3D, List[float], str] = Field( default_factory=lambda: Vector3D(x=70, y=70, z=70), description="Camera position in 3D space (accepts Vector3D, list [x,y,z], or JSON string)", ) camera_target: Union[Vector3D, List[float], str] = Field( default_factory=lambda: Vector3D(x=0, y=0, z=0), description="Point camera looks at (accepts Vector3D, list [x,y,z], or JSON string)", ) camera_up: Union[Vector3D, List[float], str] = Field( default_factory=lambda: Vector3D(x=0, y=0, z=1), description="Camera up vector (accepts Vector3D, list [x,y,z], or JSON string)", ) @field_validator("camera_position", "camera_target", "camera_up", mode="before") @classmethod def parse_camera_params(cls, v: Any) -> Vector3D: """Parse camera parameters into Vector3D objects. Accepts: - Vector3D objects - Lists/tuples of 3 floats: [x, y, z] - JSON string representation: "[x, y, z]" - Dict format: {"x": x, "y": y, "z": z} """ # If it's already a Vector3D, return it if isinstance(v, Vector3D): return v # Use Vector3D's validator to handle the conversion return Vector3D.model_validate(v)
• src/openscad_mcp/server.py:625-635 (helper)

  Predefined camera configurations for standard views used when 'view' parameter is specified in render_single.
  # View presets for common perspectives with distance=200 VIEW_PRESETS = { "front": ([0, -200, 0], [0, 0, 0], [0, 0, 1]), "back": ([0, 200, 0], [0, 0, 0], [0, 0, 1]), "left": ([-200, 0, 0], [0, 0, 0], [0, 0, 1]), "right": ([200, 0, 0], [0, 0, 0], [0, 0, 1]), "top": ([0, 0, 200], [0, 0, 0], [0, 1, 0]), "bottom": ([0, 0, -200], [0, 0, 0], [0, -1, 0]), "isometric": ([200, 200, 200], [0, 0, 0], [0, 0, 1]), "dimetric": ([200, 100, 200], [0, 0, 0], [0, 0, 1]), }
• src/openscad_mcp/types.py:81-135 (schema)

  Pydantic model for 3D vectors with flexible input parsing (list, dict, JSON string) used in camera parameters for render_single.
  class Vector3D(BaseModel): """3D vector for positions and directions.""" x: float = Field(..., description="X coordinate") y: float = Field(..., description="Y coordinate") z: float = Field(..., description="Z coordinate") @model_validator(mode="before") @classmethod def parse_vector_input(cls, data: Any) -> Any: """Parse various input formats for Vector3D. Handles: - Dict format: {"x": 1, "y": 2, "z": 3} - List format: [1, 2, 3] - String representation of list: "[1, 2, 3]" - String representation of dict: '{"x": 1, "y": 2, "z": 3}' """ # If it's already a dict with x, y, z keys, return as is if isinstance(data, dict) and "x" in data and "y" in data and "z" in data: return data # If it's a string, try to parse it as JSON if isinstance(data, str): try: # Remove any whitespace and try to parse data = data.strip() parsed = json.loads(data) # If parsed result is a list if isinstance(parsed, list) and len(parsed) == 3: return {"x": parsed[0], "y": parsed[1], "z": parsed[2]} # If parsed result is a dict elif isinstance(parsed, dict): return parsed except (json.JSONDecodeError, ValueError): # If JSON parsing fails, it might be a malformed string raise ValueError(f"Cannot parse '{data}' as a valid Vector3D") # If it's a list or tuple with 3 elements if isinstance(data, (list, tuple)) and len(data) == 3: return {"x": data[0], "y": data[1], "z": data[2]} # If none of the above, return as is and let Pydantic handle it return data def to_tuple(self) -> Tuple[float, float, float]: """Convert to tuple format.""" return (self.x, self.y, self.z) @classmethod def from_tuple(cls, values: Tuple[float, float, float]) -> "Vector3D": """Create from tuple.""" return cls(x=values[0], y=values[1], z=values[2])