claude mcp add -s user imagen \
  -e OPENAI_API_KEY=sk-... \
  -e GEMINI_API_KEY=AI... \
  -- npx -y imagen-mcp

claude mcp list

{
  "mcpServers": {
    "imagen": {
      "command": "npx",
      "args": ["-y", "imagen-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "GEMINI_API_KEY": "AI..."
      }
    }
  }
}

codex mcp add imagen -- npx -y imagen-mcp

[mcp_servers.imagen]
command = "npx"
args = ["-y", "imagen-mcp"]

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

{
  "mcpServers": {
    "imagen": {
      "command": "npx",
      "args": ["-y", "imagen-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "GEMINI_API_KEY": "AI..."
      }
    }
  }
}

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

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

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

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

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

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

# Reference images for style/character consistency (base64 encoded)
generate_image(prompt="...", reference_images=["base64..."])

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

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

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

# Clone and install (runtime + dev tooling)
git clone https://github.com/michaeljabbour/imagen-mcp.git
cd imagen-mcp
pip install -e ".[dev]"          # or: uv sync --extra dev

# Install pre-commit hooks (ruff + mypy)
pre-commit install

# Run the full quality gate (same as CI)
ruff format --check src/ tests/
ruff check src/ tests/
mypy src/
pytest --cov=src --cov-fail-under=80

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

# Run over HTTP instead of stdio
IMAGEN_MCP_TRANSPORT=streamable-http imagen-mcp

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

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

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