---
slug: "openscad-3d-model-generator"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/jhacksman/openscad-mcp-server@main/README.md"
repo: "https://github.com/jhacksman/openscad-mcp-server"
source_file: "README.md"
branch: "main"
---
# OpenSCAD MCP Server

A Model Context Protocol (MCP) server that enables users to generate 3D models from text descriptions or images, with a focus on creating parametric 3D models using multi-view reconstruction and OpenSCAD.

## Features

- **AI Image Generation**: Generate images from text descriptions using Google Gemini or Venice.ai APIs
- **Multi-View Image Generation**: Create multiple views of the same 3D object for reconstruction
- **Image Approval Workflow**: Review and approve/deny generated images before reconstruction
- **3D Reconstruction**: Convert approved multi-view images into 3D models using CUDA Multi-View Stereo
- **Remote Processing**: Process computationally intensive tasks on remote servers within your LAN
- **OpenSCAD Integration**: Generate parametric 3D models using OpenSCAD
- **Parametric Export**: Export models in formats that preserve parametric properties (CSG, AMF, 3MF, SCAD)
- **3D Printer Discovery**: Optional network printer discovery and direct printing

## Architecture

The server is built using the Python MCP SDK and follows a modular architecture:

```
openscad-mcp-server/
├── src/
│   ├── main.py                  # Main application
│   ├── main_remote.py           # Remote CUDA MVS server
│   ├── ai/                      # AI integrations
│   │   ├── gemini_api.py        # Google Gemini API for image generation
│   │   └── venice_api.py        # Venice.ai API for image generation (optional)
│   ├── models/                  # 3D model generation
│   │   ├── cuda_mvs.py          # CUDA Multi-View Stereo integration
│   │   └── code_generator.py    # OpenSCAD code generation
│   ├── workflow/                # Workflow components
│   │   ├── image_approval.py    # Image approval mechanism
│   │   └── multi_view_to_model_pipeline.py  # Complete pipeline
│   ├── remote/                  # Remote processing
│   │   ├── cuda_mvs_client.py   # Client for remote CUDA MVS processing
│   │   ├── cuda_mvs_server.py   # Server for remote CUDA MVS processing
│   │   ├── connection_manager.py # Remote connection management
│   │   └── error_handling.py    # Error handling for remote processing
│   ├── openscad_wrapper/        # OpenSCAD CLI wrapper
│   ├── visualization/           # Preview generation and web interface
│   ├── utils/                   # Utility functions
│   └── printer_discovery/       # 3D printer discovery
├── scad/                        # Generated OpenSCAD files
├── output/                      # Output files (models, previews)
│   ├── images/                  # Generated images
│   ├── multi_view/              # Multi-view images
│   ├── approved_images/         # Approved images for reconstruction
│   └── models/                  # Generated 3D models
├── templates/                   # Web interface templates
└── static/                      # Static files for web interface
```

## Installation

1. Clone the repository:
   ```
   git clone https://github.com/jhacksman/OpenSCAD-MCP-Server.git
   cd OpenSCAD-MCP-Server
   ```

2. Create a virtual environment:
   ```
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. Install dependencies:
   ```
   pip install -r requirements.txt
   ```

4. Install OpenSCAD:
   - Ubuntu/Debian: `sudo apt-get install openscad`
   - macOS: `brew install openscad`
   - Windows: Download from [openscad.org](https://openscad.org/downloads.html)

5. Install CUDA Multi-View Stereo:
   ```
   git clone https://github.com/fixstars/cuda-multi-view-stereo.git
   cd cuda-multi-view-stereo
   mkdir build && cd build
   cmake ..
   make
   ```

6. Set up API keys:
   - Create a `.env` file in the root directory
   - Add your API keys:
     ```
     GEMINI_API_KEY=your-gemini-api-key
     VENICE_API_KEY=your-venice-api-key  # Optional
     REMOTE_CUDA_MVS_API_KEY=your-remote-api-key  # For remote processing
     ```

## Remote Processing Setup

The server supports remote processing of computationally intensive tasks, particularly CUDA Multi-View Stereo reconstruction. This allows you to offload processing to more powerful machines within your LAN.

### Server Setup (on the machine with CUDA GPU)

1. Install CUDA Multi-View Stereo on the server machine:
   ```
   git clone https://github.com/fixstars/cuda-multi-view-stereo.git
   cd cuda-multi-view-stereo
   mkdir build && cd build
   cmake ..
   make
   ```

2. Start the remote CUDA MVS server:
   ```
   python src/main_remote.py
   ```

3. The server will automatically advertise itself on the local network using Zeroconf.

### Client Configuration

1. Configure remote processing in your `.env` file:
   ```
   REMOTE_CUDA_MVS_ENABLED=True
   REMOTE_CUDA_MVS_USE_LAN_DISCOVERY=True
   REMOTE_CUDA_MVS_API_KEY=your-shared-secret-key
   ```

2. Alternatively, you can specify a server URL directly:
   ```
   REMOTE_CUDA_MVS_ENABLED=True
   REMOTE_CUDA_MVS_USE_LAN_DISCOVERY=False
   REMOTE_CUDA_MVS_SERVER_URL=http://server-ip:8765
   REMOTE_CUDA_MVS_API_KEY=your-shared-secret-key
   ```

### Remote Processing Features

- **Automatic Server Discovery**: Find CUDA MVS servers on your local network
- **Job Management**: Upload images, track job status, and download results
- **Fault Tolerance**: Automatic retries, circuit breaker pattern, and error tracking
- **Authentication**: Secure API key authentication for all remote operations
- **Health Monitoring**: Continuous server health checks and status reporting

## Usage

1. Start the server:
   ```
   python src/main.py
   ```

2. The server will start on http://localhost:8000

3. Use the MCP tools to interact with the server:

   - **generate_image_gemini**: Generate an image using Google Gemini API
     ```json
     {
       "prompt": "A low-poly rabbit with black background",
       "model": "gemini-2.0-flash-exp-image-generation"
     }
     ```

   - **generate_multi_view_images**: Generate multiple views of the same 3D object
     ```json
     {
       "prompt": "A low-poly rabbit",
       "num_views": 4
     }
     ```

   - **create_3d_model_from_images**: Create a 3D model from approved multi-view images
     ```json
     {
       "image_ids": ["view_1", "view_2", "view_3", "view_4"],
       "output_name": "rabbit_model"
     }
     ```

   - **create_3d_model_from_text**: Complete pipeline from text to 3D model
     ```json
     {
       "prompt": "A low-poly rabbit",
       "num_views": 4
     }
     ```

   - **export_model**: Export a model to a specific format
     ```json
     {
       "model_id": "your-model-id",
       "format": "obj"  // or "stl", "ply", "scad", etc.
     }
     ```

   - **discover_remote_cuda_mvs_servers**: Find CUDA MVS servers on your network
     ```json
     {
       "timeout": 5
     }
     ```

   - **get_remote_job_status**: Check the status of a remote processing job
     ```json
     {
       "server_id": "server-id",
       "job_id": "job-id"
     }
     ```

   - **download_remote_model_result**: Download a completed model from a remote server
     ```json
     {
       "server_id": "server-id",
       "job_id": "job-id",
       "output_name": "model-name"
     }
     ```

   - **discover_printers**: Discover 3D printers on the network
     ```json
     {}
     ```

   - **print_model**: Print a model on a connected printer
     ```json
     {
       "model_id": "your-model-id",
       "printer_id": "your-printer-id"
     }
     ```

## Image Generation Options

The server supports multiple image generation options:

1. **Google Gemini API** (Default): Uses the Gemini 2.0 Flash Experimental model for high-quality image generation
   - Supports multi-view generation with consistent style
   - Requires a Google Gemini API key

2. **Venice.ai API** (Optional): Alternative image generation service
   - Supports various models including flux-dev and fluently-xl
   - Requires a Venice.ai API key

3. **User-Provided Images**: Skip image generation and use your own images
   - Upload images directly to the server
   - Useful for working with existing photographs or renders

## Multi-View Workflow

The server implements a multi-view workflow for 3D reconstruction:

1. **Image Generation**: Generate multiple views of the same 3D object
2. **Image Approval**: Review and approve/deny each generated image
3. **3D Reconstruction**: Convert approved images into a 3D model using CUDA MVS
   - Can be processed locally or on a remote server within your LAN
4. **Model Refinement**: Optionally refine the model using OpenSCAD

## Remote Processing Workflow

The remote processing workflow allows you to offload computationally intensive tasks to more powerful machines:

1. **Server Discovery**: Automatically discover CUDA MVS servers on your network
2. **Image Upload**: Upload approved multi-view images to the remote server
3. **Job Processing**: Process the images on the remote server using CUDA MVS
4. **Status Tracking**: Monitor the job status and progress
5. **Result Download**: Download the completed 3D model when processing is finished

## Supported Export Formats

The server supports exporting models in various formats:

- **OBJ**: Wavefront OBJ format (standard 3D model format)
- **STL**: Standard Triangle Language (for 3D printing)
- **PLY**: Polygon File Format (for point clouds and meshes)
- **SCAD**: OpenSCAD source code (for parametric models)
- **CSG**: OpenSCAD CSG format (preserves all parametric properties)
- **AMF**: Additive Manufacturing File Format (preserves some metadata)
- **3MF**: 3D Manufacturing Format (modern replacement for STL with metadata)

## Web Interface

The server provides a web interface for:

- Generating and approving multi-view images
- Previewing 3D models from different angles
- Downloading models in various formats

Access the interface at http://localhost:8000/ui/

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.