rmrfslashbin/mcp-server-images

MCP Server - Images

A Model Context Protocol (MCP) server for AI-powered image generation using Stability AI and Black Forest Labs APIs.

Features

• Multi-provider support: Stability AI (Stable Diffusion) and Black Forest Labs (Flux models)
• Direct generation: Accepts optimized prompts directly from calling LLM (no dual pipes)
• Flexible filename templates: Customizable output filenames with timestamp, provider, model, and content-based variables
• Comprehensive metadata: Full tracking of generation parameters, checksums, and provenance
• Professional error handling: Detailed error reporting and retry mechanisms
• MCP standard compliance: Works with any MCP-compatible client

Quick Start

Installation

# Clone the repository
git clone https://github.com/rmrfslashbin/mcp-server-images.git
cd mcp-server-images

# Install dependencies
uv sync

Configuration

Configure via environment variables:

STABILITY_API_KEY=sk-...     # Required for Stability AI
BFL_API_KEY=...              # Required for Black Forest Labs

Usage with MCP Client

# Run the server
uv run mcp-server-images

# Or via Python
python -m mcp_server_images

MCP Tools

generate_image

Generate images from text prompts with AI-optimized prompting.

Parameters:

• prompt (required): Detailed, optimized text description of the image to generate
• negative_prompt (optional): Things to avoid in the image (Stability AI only)
• provider (optional): "stability" or "bfl" (default: "stability")
• model (optional): Specific model to use (e.g., "sd3.5-large", "flux-pro-1.1")
• aspect_ratio (optional): Image aspect ratio (default: "1:1")
• cfg_scale (optional): Classifier free guidance scale 1.0-10.0 (Stability AI only)
• seed (optional): Seed for reproducible generation
• output_dir (optional): Output directory (default: "./images")
• filename_template (optional): Template for generated filenames

Example:

{
  "name": "generate_image",
  "arguments": {
    "prompt": "A majestic mountain landscape at golden hour, with a pristine lake reflecting the warm sunset colors, ancient pine trees framing the composition, volumetric lighting through misty atmosphere, highly detailed digital painting style",
    "negative_prompt": "blurry, low quality, oversaturated, distorted, artificial",
    "provider": "stability",
    "model": "sd3.5-large",
    "aspect_ratio": "16:9",
    "cfg_scale": 7.5,
    "filename_template": "{{.Timestamp}}-{{.Provider}}-{{.Subject}}"
  }
}

Filename Templates

Customize output filenames using template variables:

• {{.Timestamp}}: mmddyy.hhmmss format
• {{.Date}}: mmddyy format
• {{.Time}}: hhmmss format
• {{.Provider}}: "stability" or "bfl"
• {{.Model}}: Model name (e.g., "sd3.5-large")
• {{.Subject}}: Cleaned main subject from prompt
• {{.Hash}}: Short hash of the prompt
• {{.Counter}}: Auto-incrementing counter

Example templates:

• "{{.Timestamp}}-{{.Subject}}" → 071825.143022-mountain_landscape.png
• "{{.Date}}.{{.Time}}-{{.Provider}}-{{.Model}}" → 071825.143022-stability-sd35-large.png
• "img_{{.Counter}}_{{.Hash}}" → img_001_a7b2c9d8.png

Supported Providers

Stability AI

• Models: sd3-large, sd3-large-turbo, sd3-medium, sd3.5-large, sd3.5-large-turbo, sd3.5-medium
• Features: Negative prompts, CFG scale control, multiple aspect ratios
• API: Stability AI REST API v2

Black Forest Labs

• Models: flux-pro-1.1, flux-pro-1.1-ultra, flux-pro, flux-dev
• Features: High-quality generation, fast turnaround
• API: BFL REST API v1

Integration

With Chatterbox

Add to your config.yaml:

mcp:
  servers:
    images:
      command: "uv"
      args: ["run", "mcp-server-images"]
      env:
        STABILITY_API_KEY: "sk-..."
        BFL_API_KEY: "..."
      config:
        output_dir: "./images"
        filename_template: "{{.Timestamp}}-{{.Provider}}-{{.Subject}}"

With Other MCP Clients

This server works with any MCP-compatible client including:

• Claude Desktop
• Cline (VS Code extension)
• Continue (VS Code extension)
• Custom MCP clients

Development

# Install development dependencies
uv sync --dev

# Run tests
uv run pytest

# Format code
uv run ruff format .

# Lint code  
uv run ruff check .

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Related Projects

• chatterbox - AI chat interface with MCP support
• mkimg - Original Python image generation pipeline
• MCP Servers - Official MCP server implementations