Stable Fast 3D MCP Server

Stable Fast 3D MCP Server

An MCP (Model Context Protocol) server that provides tools to generate 3D models from images using Stability AI's Stable Fast 3D API.

Features

• Generate 3D models from images: Convert any 2D image into a high-quality 3D GLB file
• Customizable parameters: Control texture resolution, mesh complexity, and more
• Base64 support: Generate from base64-encoded images for programmatic use
• Credit balance check: Monitor your Stability AI account balance

Prerequisites

• Python 3.10 or higher
• A Stability AI API key (get one at https://platform.stability.ai/account/keys)

Installation

1. Clone or download this repository:

cd mcp-stable-fast-3d

1. Install dependencies:

pip install -e .

1. Set your Stability AI API key as an environment variable:

Windows (PowerShell): ``powershell $env:STABILITY_API_KEY = "sk-your-api-key-here" ``

Windows (Command Prompt): ``cmd set STABILITY_API_KEY=sk-your-api-key-here ``

Linux/macOS: ``bash export STABILITY_API_KEY="sk-your-api-key-here" ``

Usage

Running the Server

python server.py

Or using the installed command: ``bash mcp-stable-fast-3d ``

Configuring with Claude Desktop

Add this to your Claude Desktop configuration file (claude_desktop_config.json):

Using uvx from GitHub (recommended - no installation required): ``json { "mcpServers": { "stable-fast-3d": { "command": "uvx", "args": ["--from", "git+https://github.com/rikturnbull/mcp-stable-fast-3d", "mcp-stable-fast-3d"], "env": { "STABILITY_API_KEY": "sk-your-api-key-here" } } } } ``

Using local installation with Python:

Windows: ``json { "mcpServers": { "stable-fast-3d": { "command": "python", "args": ["C:\\path\\to\\mcp-stable-fast-3d\\server.py"], "env": { "STABILITY_API_KEY": "sk-your-api-key-here" } } } } ``

macOS/Linux: ``json { "mcpServers": { "stable-fast-3d": { "command": "python", "args": ["/path/to/mcp-stable-fast-3d/server.py"], "env": { "STABILITY_API_KEY": "sk-your-api-key-here" } } } } ``

Configuring with VS Code (GitHub Copilot)

Add to your VS Code settings.json or create .vscode/mcp.json in your project:

Using uvx from GitHub (recommended): ``json { "servers": { "stable-fast-3d": { "command": "uvx", "args": ["--from", "git+https://github.com/rikturnbull/mcp-stable-fast-3d", "mcp-stable-fast-3d"], "env": { "STABILITY_API_KEY": "sk-your-api-key-here" } } } } ``

Using local virtual environment: ``json { "servers": { "stable-fast-3d": { "command": "c:\\path\\to\\mcp-stable-fast-3d\\.venv\\Scripts\\python.exe", "args": ["c:\\path\\to\\mcp-stable-fast-3d\\server.py"], "env": { "STABILITY_API_KEY": "sk-your-api-key-here" } } } } ``

Available Tools

generate_3d_model

Generate a 3D model (GLB file) from a 2D image file.

Parameters: | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | image_path | string | Yes | - | Path to input image (JPEG, PNG, or WebP) | | output_path | string | No | Same as input with .glb extension | Path for output GLB file | | texture_resolution | string | No | "1024" | Texture resolution: "512", "1024", or "2048" | | foreground_ratio | float | No | 0.85 | Padding ratio (0.1 to 1.0) | | remesh | string | No | "none" | Remeshing: "none", "quad", or "triangle" | | vertex_count | int | No | -1 | Target vertex count (-1 for no limit) |

Example: `` Generate a 3D model from the image at C:\images\cat-statue.png with high resolution textures ``

generate_3d_model_from_base64

Generate a 3D model from a base64-encoded image.

Parameters: | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | image_base64 | string | Yes | - | Base64-encoded image data | | image_format | string | Yes | - | Image format: "jpeg", "png", or "webp" | | output_path | string | Yes | - | Path for output GLB file | | texture_resolution | string | No | "1024" | Texture resolution | | foreground_ratio | float | No | 0.85 | Padding ratio | | remesh | string | No | "none" | Remeshing algorithm | | vertex_count | int | No | -1 | Target vertex count |

check_api_balance

Check your Stability AI account credit balance.

API Costs

• Stable Fast 3D: 10 credits per successful generation
• Failed generations are not charged

Input Image Guidelines

For best results:

• Use images with a clear, well-lit subject
• The object should be centered in the frame
• Clean backgrounds work better
• Image dimensions should be between 64×64 and 2048×2048 pixels
• Total pixel count must be between 4,096 and 4,194,304 pixels

Output Format

The generated 3D model is saved as a GLB file (glTF Binary), which includes:

• 3D mesh geometry
• Albedo (color) texture map
• Normal texture map

GLB files can be viewed in:

• Windows 3D Viewer
• Blender
• Unity/Unreal Engine
• Most modern web browsers (with appropriate viewers)

Error Handling

The server handles common errors:

• Missing API key
• Invalid image formats
• API rate limiting (150 requests per 10 seconds)
• File not found errors
• Network timeouts

License

MIT License