OpenSCAD MCP Server

A production-ready Model Context Protocol (MCP) server that provides OpenSCAD 3D rendering capabilities to AI assistants and LLM applications. Built with FastMCP for robust, scalable performance.

🎯 Zero-Installation Execution

Run directly from GitHub without any setup:

uv run --with git+https://github.com/quellant/openscad-mcp.git openscad-mcp

Perfect for MCP clients, CI/CD pipelines, and instant deployment scenarios!

🚀 Quick Start

Zero-Installation Execution with `uv`

No installation required! Run directly from GitHub:

# Run via script entry point (recommended)
uv run --with git+https://github.com/quellant/openscad-mcp.git openscad-mcp

# Or run as Python module
uv run --with git+https://github.com/quellant/openscad-mcp.git python -m openscad_mcp

Traditional Installation (Optional)

# Clone and run locally
git clone https://github.com/quellant/openscad-mcp.git
cd openscad-mcp
uv run openscad-mcp

Configure with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Option 1: Direct from GitHub (Recommended)

{
  "mcpServers": {
    "openscad": {
      "command": "uv",
      "args": ["run", "--with", "git+https://github.com/quellant/openscad-mcp.git", "openscad-mcp"],
      "env": {
        "OPENSCAD_PATH": "/usr/bin/openscad"
      }
    }
  }
}

Option 2: Local Installation

{
  "mcpServers": {
    "openscad": {
      "command": "uv",
      "args": ["run", "openscad-mcp"],
      "cwd": "/path/to/openscad-mcp",
      "env": {
        "OPENSCAD_PATH": "/usr/bin/openscad"
      }
    }
  }
}

🔒 Security: --allowedTools Requirement

IMPORTANT: When using the OpenSCAD MCP server with Claude CLI or other MCP clients, you MUST explicitly grant permissions using the --allowedTools flag for security. This prevents unauthorized tool usage and ensures controlled access to server capabilities.

Required Permissions

The OpenSCAD MCP server requires explicit permission for each tool:

openscad-mcp:check_openscad - Permission to check OpenSCAD installation
openscad-mcp:render_single - Permission to render single views
openscad-mcp:render_perspectives - Permission to render multiple perspectives

Example Usage with Claude CLI

# Start the server with uv and grant permissions
# (Create mcp-config.json with uv configuration first)

# Grant permission for a single tool
claude --config mcp-config.json \
       --allowedTools openscad-mcp:check_openscad \
       "Check if OpenSCAD is installed"

# Grant permission for multiple tools
claude --config mcp-config.json \
       --allowedTools openscad-mcp:check_openscad,openscad-mcp:render_single \
       "Render a cube with dimensions 30x30x30"

# Grant full permissions for all OpenSCAD tools
claude --config mcp-config.json \
       --allowedTools openscad-mcp:check_openscad,openscad-mcp:render_single,openscad-mcp:render_perspectives \
       "Create a gear model and show it from multiple angles"

Create mcp-config.json for Claude CLI:

{
  "mcpServers": {
    "openscad-mcp": {
      "command": "uv",
      "args": ["run", "--with", "git+https://github.com/quellant/openscad-mcp.git", "openscad-mcp"],
      "env": {
        "OPENSCAD_PATH": "/usr/bin/openscad"
      }
    }
  }
}

Testing with Permissions

Use the provided test script to verify proper permission configuration:

# Run all permission tests
./test_claude_with_permissions.sh all

# Test individual tools
./test_claude_with_permissions.sh check        # Test check_openscad only
./test_claude_with_permissions.sh single       # Test render_single only
./test_claude_with_permissions.sh perspectives # Test render_perspectives only

# Launch interactive session with full permissions
./test_claude_with_permissions.sh interactive

# Show usage examples
./test_claude_with_permissions.sh examples

✨ Features

🎯 Production-Ready: 100% test success rate with comprehensive integration testing
🔧 Single View Rendering: Render OpenSCAD models from any camera angle with full control
📐 Multiple Perspectives: Generate standard orthographic and isometric views automatically
🎬 Animation Support: Create turntable animations for 360° model visualization
⚡ Async Processing: Non-blocking renders using FastMCP framework for optimal performance
🖼️ Base64 Encoding: Images returned as base64-encoded PNGs for seamless integration
✅ Verified Compatibility: Fully compatible with FastMCP 2.11.3 and Pydantic 2.11.7

📋 Prerequisites

Python 3.10+ (required for FastMCP 2.11.3)
OpenSCAD (Download from openscad.org)
uv (Install from docs.astral.sh) - Only needed for zero-installation execution

No additional Python packages required when using uv - all dependencies are handled automatically!

📦 Installation

Method 1: Zero-Installation with `uv` (Recommended)

No installation required! Just run directly:

# Run directly from GitHub - uv handles everything automatically
uv run --with git+https://github.com/quellant/openscad-mcp.git openscad-mcp

# All dependencies (FastMCP 2.11.3, Pydantic 2.11.7, etc.) are resolved and installed automatically

Method 2: Local Development with `uv`

# Clone for local development
git clone https://github.com/quellant/openscad-mcp.git
cd openscad-mcp

# Run with uv (installs dependencies automatically)
uv run openscad-mcp

# Or run as module
uv run python -m openscad_mcp

Method 3: Traditional pip Installation

# Only if you can't use uv
git clone https://github.com/quellant/openscad-mcp.git
cd openscad-mcp
pip install -e .
python -m openscad_mcp

⚙️ Configuration

Environment Variables

Create a .env file in the project root:

# OpenSCAD Configuration
OPENSCAD_PATH=/usr/bin/openscad  # Path to OpenSCAD executable
OPENSCAD_TIMEOUT=30               # Timeout for rendering operations (seconds)

# Server Configuration
MCP_SERVER_NAME=openscad-mcp
MCP_SERVER_VERSION=1.0.0
MCP_SERVER_TRANSPORT=stdio        # Transport: stdio, sse, or http

# Rendering Configuration
MCP_RENDER_MAX_CONCURRENT=4       # Max concurrent renders
MCP_RENDER_DEFAULT_WIDTH=800      # Default image width
MCP_RENDER_DEFAULT_HEIGHT=600     # Default image height

Configuration File (Optional)

Create config.yaml for advanced configuration:

server:
  name: "OpenSCAD MCP Server"
  version: "1.0.0"
  transport: stdio

openscad:
  timeout: 30
  default_color_scheme: "Cornfield"

rendering:
  max_concurrent: 4
  default_width: 800
  default_height: 600

🛠️ Available MCP Tools

1. `render_single`

Render a single view of an OpenSCAD model with complete camera control.

Parameters:

Parameter	Type	Required	Description
`scad_content`	string	No*	OpenSCAD code to render
`scad_file`	string	No*	Path to .scad file
`camera_position`	[x,y,z]	No	Camera position (default: [30,30,30])
`camera_target`	[x,y,z]	No	Look-at point (default: [0,0,0])
`camera_up`	[x,y,z]	No	Up vector (default: [0,0,1])
`image_size`	[w,h]	No	Image dimensions in pixels
`color_scheme`	string	No	OpenSCAD color scheme
`variables`	dict	No	Variables to pass to OpenSCAD
`auto_center`	bool	No	Auto-center the model

*Either scad_content or scad_file must be provided

Example Request:

{
  "tool": "render_single",
  "arguments": {
    "scad_content": "cube([10, 10, 10]);",
    "camera_position": [30, 30, 30],
    "image_size": [800, 600],
    "color_scheme": "Cornfield"
  }
}

Example Response:

{
  "success": true,
  "image": "data:image/png;base64,iVBORw0KGgo...",
  "metadata": {
    "width": 800,
    "height": 600,
    "render_time": 1.23
  }
}

2. `render_perspectives`

Generate multiple standard views of a model (front, back, left, right, top, bottom, isometric).

Parameters:

Parameter	Type	Required	Description
`scad_content`	string	No*	OpenSCAD code to render
`scad_file`	string	No*	Path to .scad file
`distance`	float	No	Camera distance from origin
`image_size`	[w,h]	No	Image dimensions for each view
`variables`	dict	No	Variables to pass to OpenSCAD
`views`	list	No	Specific views to render

Example Request:

{
  "tool": "render_perspectives",
  "arguments": {
    "scad_file": "model.scad",
    "views": ["front", "isometric", "top"],
    "distance": 200,
    "image_size": [400, 400]
  }
}

3. `check_openscad`

Verify OpenSCAD installation and get version information.

Parameters:

Parameter	Type	Required	Description
`include_paths`	bool	No	Include searched paths in response

Example Request:

{
  "tool": "check_openscad",
  "arguments": {
    "include_paths": true
  }
}

📚 MCP Resources

`resource://server/info`

Get server configuration and capabilities.

Returns:

Server version and status
OpenSCAD version and path
Rendering capabilities
Active operations count
Configuration details

🏗️ Architecture

The server implements a clean architecture pattern:

┌─────────────────────────────────────┐
│         MCP Client (Claude)         │
└─────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────┐
│    FastMCP Server (Presentation)    │
│        - MCP Protocol Handler       │
│        - Tool Decorators            │
└─────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────┐
│     Application Layer (Business)    │
│        - Rendering Logic            │
│        - Parameter Validation       │
└─────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────┐
│   Infrastructure Layer (External)   │
│        - OpenSCAD CLI               │
│        - File I/O Operations        │
└─────────────────────────────────────┘

🧪 Testing

The server has achieved 100% test success rate across all integration tests:

# Run comprehensive test suite
python comprehensive_test.py

# Run MCP tools integration test
python test_mcp_tools.py

# Run server startup test
python test_server_startup.py

See Test Report for detailed results.

🔧 Development

Project Structure

openscad-mcp-server/
├── src/
│   └── openscad_mcp/
│       ├── __init__.py         # Package initialization
│       ├── __main__.py          # Entry point
│       ├── server.py            # FastMCP server implementation
│       ├── types.py             # Pydantic models & types
│       └── utils/
│           └── config.py        # Configuration management
├── tests/                       # Test suite
├── pyproject.toml              # Project configuration
├── README.md                   # This file
├── CHANGELOG.md               # Version history
├── API.md                     # Detailed API documentation
└── .env.example               # Environment template

Extending the Server

To add new rendering capabilities:

Define parameter types in types.py:

class CustomRenderParams(BaseModel):
    # Your parameters here
    pass

Add tool function in server.py:

@mcp.tool
async def custom_render(params: CustomRenderParams) -> RenderResult:
    """Your custom rendering logic"""
    # Implementation
    pass

Update documentation in API.md

🐛 Troubleshooting

OpenSCAD Not Found

# Check OpenSCAD installation
which openscad

# Set environment variable
export OPENSCAD_PATH=/path/to/openscad

# Or add to .env file
OPENSCAD_PATH=/usr/local/bin/openscad

Permission Errors

# Ensure execute permissions
chmod +x /path/to/openscad

Rendering Timeouts

Increase timeout in configuration:

export OPENSCAD_TIMEOUT=60  # 60 seconds

FastMCP Compatibility Issues

Ensure correct versions:

pip install fastmcp==2.11.3 pydantic==2.11.7

📈 Performance

Single view rendering: ~1-3 seconds (complexity dependent)
Multiple perspectives: ~5-10 seconds for 8 views
Base64 encoding: < 0.1s overhead
Memory footprint: ~50 MB base + 10-20 MB per render
Concurrent renders: Up to 4 (configurable)

🚦 Production Status

✅ Ready for Production

All tests passing (100% success rate)
FastMCP 2.11.3 compatibility verified
Comprehensive error handling
Async operation support
Resource management implemented
Documentation complete

📝 License

MIT License - See LICENSE file for details

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📮 Support

Issues: GitHub Issues
Documentation: Full API Documentation
Test Report: Integration Test Results

🙏 Acknowledgments

FastMCP - The excellent MCP framework
OpenSCAD - The programmable CAD software
Model Context Protocol - The MCP specification

Version: 1.0.0 | Status: Production Ready | Last Updated: 2025-08-25

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Enables 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.

Related MCP Servers

Sketchfab MCP Server
gregkop
A
security
F
license
A
quality
Allows interaction with Sketchfab's 3D model platform through Claude or Cursor, enabling users to search, view details, and download 3D models directly from the AI interface.
Last updated -
4
296
27
OpenSCAD MCP Server
jhacksman
-
security
F
license
-
quality
Enables users to generate parametric 3D models from text descriptions or images using multi-view reconstruction and OpenSCAD, with support for AI image generation and remote processing.
Last updated -
75
mcp-freecad
jango-blockchained
-
security
A
license
-
quality
This project provides a robust integration between AI assistants and FreeCAD CAD software using the Model Context Protocol (MCP). It allows external applications to interact with FreeCAD through a standardized interface, offering multiple connection methods and specialized tools.
Last updated -
11
MIT License
Fusion 360 MCP Integration
sockcymbal
-
security
F
license
-
quality
Enables AI assistants to interact programmatically with Autodesk Fusion 360 for creating parametric 3D models through simple API calls.
Last updated -
13

View all related MCP servers