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

Related MCP server: 3D Asset Processing MCP

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

2. Install dependencies:

pip install -e .

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

Windows (PowerShell):

$env:STABILITY_API_KEY = "sk-your-api-key-here"

Windows (Command Prompt):

set STABILITY_API_KEY=sk-your-api-key-here

Linux/macOS:

export STABILITY_API_KEY="sk-your-api-key-here"

Usage

Running the Server

python server.py

Or using the installed command:

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):

{
  "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:

{
  "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:

{
  "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):

{
  "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:

{
  "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:

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:

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