marc-shade/image-gen-mcp

Image Generation MCP Server

Multi-provider image generation for AGI visual communication with automatic fallback.

Part of the Agentic System - a 24/7 autonomous AI framework with persistent memory.

Multi-provider image generation for AGI visual communication.

Features

• Multi-Provider Support: Automatic fallback across 5 providers
• FREE Default: Pollinations.ai requires no API key
• Pixel Art Mode: Specialized generation for sprites and game assets
• Auto-Save: Generated images automatically saved to disk
• Cost Tracking: Monitor usage and costs per provider

Providers

Installation

cd ${AGENTIC_SYSTEM_PATH:-/opt/agentic}/mcp-servers/image-gen-mcp
pip install -e .

Configuration

Add to ~/.claude.json:

{
  "mcpServers": {
    "image-gen": {
      "command": "python",
      "args": ["-m", "image_gen_mcp.server"],
      "env": {
        "CLOUDFLARE_API_TOKEN": "your-token",
        "CLOUDFLARE_ACCOUNT_ID": "your-account-id",
        "HUGGINGFACE_API_TOKEN": "your-hf-token",
        "TOGETHER_API_KEY": "your-together-key",
        "REPLICATE_API_TOKEN": "your-replicate-token",
        "IMAGE_GEN_OUTPUT_DIR": "${AGENTIC_SYSTEM_PATH:-/opt/agentic}/generated-images"
      }
    }
  }
}

Environment Variables

MCP Tools

generate_image

Generate an image from a text prompt.

{
  "prompt": "A corgi wearing a space helmet, pixel art style",
  "width": 1024,
  "height": 1024,
  "provider": "pollinations",
  "model": "flux",
  "seed": 42,
  "save_to_file": true
}

generate_pixel_art

Specialized pixel art generation.

{
  "prompt": "cute corgi sprite, side view",
  "style": "nes",
  "size": 64,
  "colors": 16
}

Styles: nes, snes, gameboy, modern, isometric

list_providers

List all providers with status.

list_models

List models for a provider.

{
  "provider": "huggingface"
}

get_provider_status

Health check for a provider.

save_image

Save base64 image to file.

Models by Provider

Pollinations.ai

• flux (default) - High quality
• flux-realism - Photorealistic
• flux-anime - Anime style
• flux-3d - 3D renders
• turbo - Fast generation

Cloudflare Workers AI

• sdxl - Stable Diffusion XL
• sdxl-lightning - Fast 4-step SDXL
• flux-schnell - Fast Flux
• dreamshaper - Photorealistic

Hugging Face

• sdxl - Stable Diffusion XL
• sdxl-turbo - Fast SDXL
• flux-dev - Flux development
• flux-schnell - Fast Flux
• playground-v2.5 - Aesthetic
• realvisxl - Photorealistic
• pixel-art - Pixel art specialized

Together AI

• flux-schnell - FREE tier available
• flux-dev - Higher quality
• flux-pro - Best quality
• sd3 - Stable Diffusion 3

Replicate

• flux-schnell - Fast Flux
• flux-dev - Higher quality
• flux-pro - Best quality
• sdxl - Stable Diffusion XL
• playground-v2.5 - Aesthetic

Usage Examples

Basic Image Generation

Generate an image of a mountain landscape at sunset

Pixel Art for Sprites

Generate pixel art of a corgi walking animation, NES style, 64x64

With Specific Provider

Generate a photorealistic portrait using Cloudflare's SDXL model

Output

Images are saved to IMAGE_GEN_OUTPUT_DIR with format:

{timestamp}_{prompt_snippet}_{provider}.png

Example: 20241128_143022_mountain_landscape_pollinations.png

Error Handling

The server automatically falls back through providers if one fails:

1. Try requested provider (or Pollinations)
2. If failed, try Cloudflare
3. If failed, try Together AI
4. If failed, try Hugging Face
5. If failed, try Replicate
6. Return error with all attempted providers

Future Enhancements

• Local GPU support (Flux/ComfyUI) when 12GB GPU available
• Image-to-image generation
• Inpainting and outpainting
• Upscaling
• Style transfer
• Animation generation

License

MIT

Part of the MCP Ecosystem

This server integrates with other MCP servers for comprehensive AGI capabilities:

See agentic-system-oss for the complete framework.