Which integrations are available for this server?

Generates images using Google Gemini's image models (Nano Banana Pro, Flash, Imagen 3.0) with support for photorealism, up to 4K resolution, reference images for character/style consistency, real-time data via Google Search grounding, and conversational history for iterative refinement. Generates images using OpenAI's GPT-Image-1 model, optimized for text-heavy images like menus, infographics, comics, and diagrams with excellent text rendering capabilities.

How do I use imagen-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@imagen-mcp create a logo for a coffee shop called 'Morning Brew' with a minimalist design" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

imagen-mcp

A Model Context Protocol (MCP) server for intelligent multi-provider image generation.

Python 3.10+ License: MIT

Features

Auto Provider Selection - Analyzes prompts to choose the best provider
Multi-Provider Support - OpenAI GPT-Image-1 and Google Gemini
Reference Images - Up to 14 images for character/style consistency (Gemini)
Real-time Data - Google Search grounding for current info (Gemini)
Conversational History - Iteratively refine images with context (Gemini)
High Resolution - Up to 4K output (Gemini)
Flexible Storage - Save to ~/Downloads/images/ or custom locations

Architecture

flowchart TB
    subgraph Clients["MCP Clients"]
        CD[Claude Desktop]
        CC[Claude Code CLI]
        GC[Gemini CLI]
        CX[Codex CLI]
    end

    subgraph Server["imagen-mcp Server"]
        MCP[MCP Protocol Layer]

        subgraph Tools["MCP Tools"]
            GI[generate_image]
            CI[conversational_image]
            LP[list_providers]
            LM[list_gemini_models]
        end

        subgraph Core["Core Components"]
            PS[Provider Selector]
            PR[Provider Registry]
        end

        subgraph Providers["Image Providers"]
            OAI[OpenAI Provider<br/>GPT-Image-1]
            GEM[Gemini Provider<br/>Nano Banana Pro]
        end
    end

    subgraph APIs["External APIs"]
        OAPI[OpenAI API]
        GAPI[Google Gemini API]
    end

    subgraph Storage["Local Storage"]
        DL[~/Downloads/images/]
    end

    CD & CC & GC & CX --> MCP
    MCP --> Tools
    GI & CI --> PS
    PS --> PR
    PR --> OAI & GEM
    OAI --> OAPI
    GEM --> GAPI
    OAI & GEM --> DL

Provider Comparison

Feature	OpenAI GPT-Image-1	Gemini Nano Banana Pro
Text Rendering	Excellent	Good
Photorealism	Good	Excellent
Speed	~60s	~15s
Max Resolution	1536x1024	4K
Sizes	3 options	1K, 2K, 4K
Aspect Ratios	3	10
Reference Images	No	Yes (up to 14)
Real-time Data	No	Yes (Google Search)

Use OpenAI for: Text-heavy images, menus, infographics, comics, diagrams

Use Gemini for: Portraits, product photography, 4K output, reference images

Available Models

OpenAI Models

Model ID	Description
`gpt-image-1`	Dedicated image generation model (default)
`gpt-5-image`	GPT-5 with image generation capabilities
`gpt-5.1`	Latest reasoning model (conversation orchestration)

Gemini Models

Model ID	Description
`gemini-3-pro-image-preview`	Nano Banana Pro - highest quality (default)
`gemini-2.0-flash-exp-image-generation`	Fast experimental
`imagen-3.0-generate-002`	Alternative image model

Installation

git clone https://github.com/michaeljabbour/imagen-mcp.git
cd imagen-mcp
pip install -r requirements.txt
chmod +x run.sh

Configuration

At least one API key is required. Both are recommended for auto-selection.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "imagen": {
      "command": "/path/to/imagen-mcp/run.sh",
      "args": [],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "GEMINI_API_KEY": "AI..."
      }
    }
  }
}

Note: Claude Desktop doesn't support cwd, so use the run.sh wrapper script which handles the directory change.

Restart Claude Desktop (Cmd+Q, then reopen) after editing.

Claude Code CLI

Use the CLI to add the server:

claude mcp add -s user imagen /path/to/imagen-mcp/run.sh

Then add environment variables by editing ~/.claude.json:

{
  "mcpServers": {
    "imagen": {
      "type": "stdio",
      "command": "/path/to/imagen-mcp/run.sh",
      "args": [],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "GEMINI_API_KEY": "AI..."
      }
    }
  }
}

Verify with:

claude mcp list

Reference: Claude Code MCP Documentation

Gemini CLI

Edit ~/.gemini/settings.json:

{
  "mcpServers": {
    "imagen": {
      "command": "/path/to/imagen-mcp/run.sh",
      "args": [],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "GEMINI_API_KEY": "AI..."
      }
    }
  }
}

Reference: Gemini CLI MCP Documentation

OpenAI Codex CLI

Edit ~/.codex/config.toml:

[mcp_servers.imagen]
command = "/path/to/imagen-mcp/run.sh"
args = []

[mcp_servers.imagen.env]
OPENAI_API_KEY = "sk-..."
GEMINI_API_KEY = "AI..."

Or use the CLI:

codex mcp add imagen -- /path/to/imagen-mcp/run.sh

Reference: Codex MCP Documentation

Generic MCP Client

For any MCP-compatible client:

Setting	Value
Command	`/path/to/imagen-mcp/run.sh`
Args	`[]`
Environment	`OPENAI_API_KEY`, `GEMINI_API_KEY`

The Wrapper Script

The run.sh script handles the working directory requirement:

#!/bin/bash
cd /path/to/imagen-mcp
exec python3 -m src.server "$@"

This is necessary because the server runs as a Python module (-m src.server) which requires being in the project directory.

Usage

Auto Provider Selection

The server analyzes your prompt and selects the best provider:

"Create a menu card for an Italian restaurant"  → OpenAI (text rendering)
"Professional headshot with studio lighting"    → Gemini (photorealism)
"Infographic about climate change"              → OpenAI (diagram + text)
"Product shot of perfume on marble"             → Gemini (product photography)

Manual Provider Selection

Override auto-selection with the provider parameter:

generate_image(prompt="...", provider="openai")
generate_image(prompt="...", provider="gemini")

Save Location

Specify a custom save path (directory or filename) with output_path:

# Save to specific directory (auto-generated filename)
generate_image(prompt="...", output_path="~/Desktop/logos/")

# Save to specific file
generate_image(prompt="...", output_path="~/Desktop/logos/my-logo.png")

If output_path is omitted, images are saved to ~/Downloads/images/{provider} by default (openai or gemini). Override the base directory with the OUTPUT_DIR environment variable (supports ~ and env vars).

Logs are written to ~/Downloads/images/logs/ by default (or OUTPUT_DIR/logs/ when OUTPUT_DIR is set).

Gemini-Specific Features

# High resolution
generate_image(prompt="...", size="4K")

# Specific model
generate_image(prompt="...", gemini_model="gemini-2.0-flash-exp-image-generation")

# Reference images (base64 encoded)
generate_image(prompt="...", reference_images=["base64..."])

# Real-time data
generate_image(prompt="Current weather in NYC", enable_google_search=True)

MCP Tools

Tool	Description
`generate_image`	Main tool with auto provider selection
`conversational_image`	Multi-turn refinement with history
`list_conversations`	List active conversations and their history
`list_providers`	Show available providers and capabilities
`list_gemini_models`	Query available Gemini image models

Development

# Install dev dependencies
pip install -r requirements.txt
pip install pytest pytest-asyncio

# Run tests
pytest tests/ -v

# Test server loads
python3 -c "from src.server import mcp; print('Server loads')"

# Test providers
python3 -c "from src.providers import get_provider_registry; print(get_provider_registry().list_providers())"

# Check logs (macOS)
tail -f ~/Library/Logs/Claude/mcp-server-imagen.log

Project Structure

imagen-mcp/
├── src/
│   ├── server.py              # MCP entry point
│   ├── config/
│   │   ├── constants.py       # Provider constants
│   │   └── settings.py        # Environment configuration
│   ├── providers/
│   │   ├── base.py            # Abstract provider interface
│   │   ├── openai_provider.py # OpenAI implementation
│   │   ├── gemini_provider.py # Gemini implementation
│   │   ├── selector.py        # Auto-selection logic
│   │   └── registry.py        # Provider factory
│   └── models/
│       └── input_models.py    # Pydantic input models
├── tests/
│   ├── test_selector.py       # Provider selection tests
│   ├── test_providers.py      # Provider unit tests
│   └── test_server.py         # Server integration tests
├── .github/
│   └── workflows/
│       └── ci.yml             # GitHub Actions CI
├── run.sh                     # Wrapper script for MCP clients
├── requirements.txt
├── CLAUDE.md
└── README.md

Environment Variables

Variable	Description	Required
`OPENAI_API_KEY`	OpenAI API key	One of these
`GEMINI_API_KEY`	Google Gemini API key	required
`GOOGLE_API_KEY`	Alias for GEMINI_API_KEY
`DEFAULT_PROVIDER`	Default: "auto"	No
`DEFAULT_OPENAI_SIZE`	Default: "1024x1024"	No
`DEFAULT_GEMINI_SIZE`	Default: "2K"	No
`ENABLE_GOOGLE_SEARCH`	Default: "false"	No
`OUTPUT_DIR`	Default directory for saved images	No
`IMAGEN_MCP_LOG_DIR`	Log directory override	No
`IMAGEN_MCP_LOG_LEVEL`	Log level (e.g. INFO, DEBUG)	No
`IMAGEN_MCP_LOG_PROMPTS`	Log prompts (default: false)	No

Requirements

mcp>=1.16.0
fastmcp>=2.12.5
pydantic>=2.12.3
httpx>=0.24.0
google-genai>=1.52.0
pillow>=10.4.0

License

MIT

imagen-mcp

imagen-mcp

Features

Architecture

Provider Comparison

Available Models

OpenAI Models

Gemini Models

Installation

Configuration

Claude Desktop

Claude Code CLI

Gemini CLI

OpenAI Codex CLI

Generic MCP Client

The Wrapper Script

Usage

Auto Provider Selection

Manual Provider Selection

Save Location

Gemini-Specific Features

MCP Tools

Development

Project Structure

Environment Variables

Requirements

License

Sources

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API