AI Image‑Gen MCP Server

Version 0.1.0 – MVP public release
Conforms to the Model Context Protocol spec (2025‑06‑18).

<p align="center"> <img src="assets/logo.png" alt="AI Image Generation MCP Server Logo (DALL-E 3)" width="400"> <img src="assets/logo-gpt.png" alt="AI Image Generation MCP Server Logo (GPT-Image-1)" width="400"> </p>

---

What's this?

A production‑ready MCP server that transforms state‑of‑the‑art image generators into plug‑and‑play tools for any MCP‑aware client. Currently shipping with DALL·E 3, DALL·E 2, and experimental GPT‑Image‑1 – all accessible through a unified interface.

Why MCP?

MCP is the USB‑C of AI context: one protocol, endless integrations. Ship one server, hook it into Claude Desktop, Claude Code, VS Code, or your own chatbot – the host handles UI, auth, and conversation flow.

Quick examples

| You ask | The server delivers | | ------------------------------------------------------------- | ----------------------------------------------------------- | | "Design a cyberpunk logo for my startup" | High‑res PNG via DALL·E 3 with style presets | | "Generate 5 variations of this product shot" | Batch generation via DALL·E 2 (n=5 support) | | "Create concept art for a steampunk airship" | Artistic rendering with metadata and prompt history |

If you can describe it, we can render it. 💫

---

Core MCP Concepts

This server implements all three MCP primitives:

1. Tools – generate_image with model selection, size, and style options
2. Resources – Available models and their capabilities exposed as MCP resources
3. Prompts – Built‑in templates for product_mockup and concept_art workflows

---

Feature Highlights

• Multi‑Model Support – DALL·E 3 (default), DALL·E 2, and GPT‑Image‑1 via unified API
• Smart Storage – Local cache with timestamped filenames and JSON metadata
• Flexible Sizing – From 256×256 thumbnails to 1792×1024 widescreen masterpieces
• Style Control – vivid or natural rendering (DALL·E 3)
• Batch Generation – Create up to 10 variations per prompt (DALL·E 2)
• Claude Integration – First‑class support for Desktop and Code editions

---

Architecture

graph TD
    Client["MCP Client (Claude Desktop/Code)"] -- JSON‑RPC 2.0 --> Server["Image‑Gen MCP Server"]
    Server --> Router["Model Router"]
    Router -->|OpenAI API| DALLE3["DALL·E 3"]
    Router -->|OpenAI API| DALLE2["DALL·E 2"]
    Router -->|Responses API| GPT["GPT‑Image‑1"]
    Server --> Storage["Local Storage + Metadata"]
    Storage --> Client

---

Quickstart

Prerequisites

• Python 3.11+
• OpenAI API key
• Claude Desktop or Claude Code (for MCP integration)

Installation

git clone https://github.com/krystian-ai/ai-image-gen-mcp.git
cd ai-image-gen-mcp
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[image,dev]"

Configuration

cp .env.example .env
# Edit .env and add your OpenAI API key

Key settings:

OPENAI_API_KEY=sk-...
MODEL_DEFAULT=dall-e-3
CACHE_DIR=/tmp/ai-image-gen-cache

Run Standalone

# Via MCP CLI
mcp-imageserve stdio

# Direct execution
python -m ai_image_gen_mcp.server --transport=stdio

---

Claude Desktop Integration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ai-image-gen": {
      "command": "/path/to/ai-image-gen-mcp/.venv/bin/python",
      "args": ["-m", "ai_image_gen_mcp.server", "stdio"],
      "transport": "STDIO",
      "env": {
        "PYTHONPATH": "/path/to/ai-image-gen-mcp/src",
        "OPENAI_API_KEY": "your-api-key-here"
      }
    }
  }
}

---

Claude Code Integration

Option 1: Project‑specific .mcp.json (Recommended)

Drop this in your project root:

{
  "ai-image-gen": {
    "command": "python",
    "args": ["-m", "ai_image_gen_mcp.server", "stdio"],
    "transport": "STDIO",
    "env": {
      "PYTHONPATH": "src",
      "OPENAI_API_KEY": "your-api-key-here"
    }
  }
}

Claude Code auto‑detects and loads it. ✨

Option 2: Global Config

Add to ~/.config/claude-code/settings.json for system‑wide access.

---

Model Capabilities

| Model | Sizes | Styles | Batch (n) | Speed | Notes | | ------------- | ---------------------------------------- | -------------- | --------- | ---------- | ------------------------------ | | DALL·E 3 | 1024×1024, 1792×1024, 1024×1792 | vivid, natural | 1 | Fast | Best quality, default model | | DALL·E 2 | 256×256, 512×512, 1024×1024 | N/A | 1-10 | Fast | Good for variations | | GPT‑Image‑1 | Fixed (model‑determined) | N/A | 1 | Slow (20s+) | Experimental, may timeout |

---

Usage Examples

Basic Generation

Generate a minimalist logo for a productivity app

With Parameters

Create a vivid 1792x1024 banner of a futuristic cityscape using dall-e-3

Batch Creation

Generate 5 variations of a coffee cup product photo using dall-e-2

---

Interactive HTML Demo

Explore the server's capabilities through our interactive web interface:

cd examples/html
open index.html  # macOS
# or
xdg-open index.html  # Linux
# or just open in your browser

The demo showcases:

• Live Examples – Generated images with their prompts
• Model Comparison – See outputs from DALL·E 3, DALL·E 2, and GPT-Image-1
• Interactive Gallery – Carousel of stunning AI-generated artwork
• Integration Guide – How to connect with Claude Desktop/Code

Perfect for visualizing what's possible before diving into the API!

---

Development

Testing

pytest                           # Full suite
pytest --cov=ai_image_gen_mcp   # Coverage report
python test_dalle.py            # Live API test

Code Quality

black src/        # Format
ruff check src/   # Lint
mypy src/         # Type check

Project Structure

ai-image-gen-mcp/
├── src/ai_image_gen_mcp/
│   ├── server.py          # FastMCP server entry
│   ├── models/            # Model implementations
│   └── config.py          # Environment config
├── tests/                 # Comprehensive test suite
├── examples/
│   └── html/              # Interactive web demo
├── assets/                # Logo images
└── .mcp.json             # Claude Code config

---

Troubleshooting

| Issue | Solution | | ---------------------------- | ----------------------------------------------------------- | | MCP not detected | Ensure .mcp.json exists in project root | | API key errors | Check OPENAI_API_KEY in .env or environment | | Import errors | Verify PYTHONPATH includes src/ directory | | GPT‑Image‑1 timeouts | Known issue – use DALL·E models for reliability | | Claude Desktop issues | Use full paths to venv Python executable |

---

Roadmap

| Version | Focus | Status | | ------- | ---------------------------------------------- | ------------ | | 0.1 | MVP with 3 models, local storage | ✅ Shipped | | 0.2 | S3/GCS storage, signed URLs | 🚧 Planning | | 0.3 | Stable Diffusion, ComfyUI integration | 📋 Backlog | | 0.4 | Inpainting, upscaling, style transfer | 💭 Ideas |

---

Contributing

Fork → feature branch → PR. Run pre-commit hooks. Keep the vibe technical but approachable.

---

License

MIT – see LICENSE.

---

Links

• MCP Docs – modelcontextprotocol.io
• FastMCP – github.com/jlowin/fastmcp
• OpenAI Images – platform.openai.com/docs/guides/images
• Issues – github.com/krystian-ai/ai-image-gen-mcp/issues