Gemini Image Gen MCP Server

Features

• 3 tools — generate_image, edit_image (inpainting/outpainting), upscale_image (2x/4x)

• Dual provider — AI Studio (free) or Vertex AI (GCP credits)

• Multi-model — Gemini 3.1 / 3 Pro Image, Gemini 2.5 Flash Image, and legacy Imagen 4 on Vertex AI

• Dynamic model switching — choose model per request via model parameter, no restart needed

• Built-in guides — MCP Resources with model selection tips and provider docs

• Smart error recovery — auto-suggests alternative models on quota errors

• Auto-save generated images to disk

• SOCKS proxy support out of the box

Related MCP server: Gemini Image MCP

Demo

Architecture

User Prompt → AI Assistant (Claude / Cursor) → MCP Server → Gemini API / Vertex AI
                                                   ↓
                                             Save to disk + Display

How It Works

The server handles two distinct Google APIs under one unified interface:

The server automatically selects the correct API based on the model name prefix — imagen* routes to Predict, everything else to GenerateContent. You don't need to worry about this distinction.

Quick Start

Option A: AI Studio (Free, Recommended for Getting Started)

1. Get API Key — visit https://aistudio.google.com/apikey → Create API Key → copy it

2. Configure MCP

claude mcp add --transport stdio mcp-image \
  --env GEMINI_API_KEY=your_api_key \
  -- uv --directory /path/to/mcp-image-gen run image-gen

{
  "mcpServers": {
    "mcp-image": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-image-gen", "run", "image-gen"],
      "env": {
        "GEMINI_API_KEY": "your_api_key"
      }
    }
  }
}

3. Use it — just ask your AI assistant:

"Generate an image of a dragon flying over mountains at dawn"

The image will be displayed inline and automatically saved to the output/ directory.

Option B: Vertex AI (Higher Quality, GCP Credits)

Use GCP billing with Gemini image models, optional legacy Imagen 4 generation, plus image editing and upscaling.

1. Prerequisites

• A GCP project with billing enabled (create one)

• Vertex AI API enabled (enable it)

• A GCP API key (create one)

2. Install with Vertex AI support

git clone https://github.com/kevinten-ai/mcp-image-gen.git
cd mcp-image-gen
uv sync --extra vertex

3. Configure MCP

claude mcp add --transport stdio mcp-image \
  --env GEMINI_PROVIDER=vertex-ai \
  --env GEMINI_API_KEY=your_gcp_api_key \
  --env GCP_PROJECT_ID=your-project-id \
  --env GCP_REGION=us-central1 \
  --env GEMINI_MODEL=gemini-3.1-flash-image \
  -- uv --directory /path/to/mcp-image-gen run --extra vertex image-gen

{
  "mcpServers": {
    "mcp-image": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-image-gen", "run", "--extra", "vertex", "image-gen"],
      "env": {
        "GEMINI_PROVIDER": "vertex-ai",
        "GEMINI_API_KEY": "your_gcp_api_key",
        "GCP_PROJECT_ID": "your-project-id",
        "GCP_REGION": "us-central1",
        "GEMINI_MODEL": "gemini-3.1-flash-image"
      }
    }
  }
}

Auth options: Vertex AI supports two authentication methods:

1. GCP API Key (recommended) — set GEMINI_API_KEY. Simple, no extra deps.

2. OAuth2 / ADC — run gcloud auth application-default login. The server auto-detects ADC when no API key is set. Requires --extra vertex for google-auth dependency.

Tools

generate_image — Text to Image

Generate images from text prompts.

"A cozy cafe in Paris at sunset"

edit_image — Image Editing (Vertex AI only)

Edit existing images with text instructions. Supports inpainting, outpainting, and background swap.

edit_image(prompt="Add a red hat", image_path="/path/to/photo.png")
edit_image(prompt="Replace background with beach", image_path="photo.png", edit_mode="product-image")
edit_image(prompt="Expand the sky", image_path="photo.png", mask_path="mask.png", edit_mode="outpainting")

upscale_image — Super Resolution (Vertex AI only)

Upscale images to 2x or 4x resolution.

upscale_image(image_path="/path/to/photo.png", upscale_factor="x4")

Usage Guide

Tips for Better Results

• Be specific: "A golden retriever puppy playing in autumn leaves, soft natural lighting" works better than "a dog"

• Mention style: Add terms like "digital art", "photorealistic", "watercolor", "oil painting", "anime style"

• Describe lighting: "golden hour", "dramatic lighting", "soft diffused light"

• Specify composition: "close-up portrait", "wide-angle landscape", "bird's eye view"

• No text: Image models generally struggle with rendering text. Use "No text" in prompts for cleaner results.

Choosing a Model

Per-request switching (recommended)

Pass the model parameter when calling the tool:

generate_image(prompt="a sunset landscape", model="gemini-3-pro-image")

AI assistants can dynamically pick the best model per request. If one model hits a quota limit, the error response automatically suggests an alternative.

Decision flowchart

Need an image?
  ├─ Free / no GCP account?
  │   └─ AI Studio: gemini-3.1-flash-image ✅
  │
  └─ Have GCP billing?
      ├─ Need balanced quality/speed?
      │   └─ gemini-3.1-flash-image ✅
      │
      ├─ Need stronger reasoning/composition?
      │   └─ gemini-3-pro-image
      │
      ├─ Need to edit an image?
      │   └─ edit_image tool (uses imagen-3.0-capability-001)
      │
      ├─ Need to upscale?
      │   └─ upscale_image tool (uses imagen-4.0-upscale-preview)
      │
      └─ Hit quota on one model?
          └─ Switch to another — each model has independent quota

Default via environment variable

Set GEMINI_MODEL to configure the default model used when no model parameter is passed:

# AI Studio (Gemini models)
GEMINI_MODEL=gemini-3.1-flash-image      # default, balanced
GEMINI_MODEL=gemini-3-pro-image          # stronger reasoning/composition
GEMINI_MODEL=gemini-2.5-flash-image      # fallback

# Vertex AI (Gemini + legacy Imagen models)
GEMINI_MODEL=gemini-3.1-flash-image        # default
GEMINI_MODEL=imagen-4.0-generate-001       # legacy Imagen; retires Aug 17, 2026

MCP Resources

The server exposes built-in documentation that AI assistants can automatically read:

AI assistants (Claude, etc.) can read these resources to make informed model choices without human intervention.

Custom Output Directory

--env IMAGE_OUTPUT_DIR=/absolute/path/to/your/images

Images are saved with timestamps: imagen_20260321_234225.png or gemini_20260321_234225.png.

Environment Variables

Supported Models

AI Studio (Gemini) — Free

Vertex AI (Imagen) — GCP Credits

Vertex AI — Specialized Models

Key insight: Each model has its own independent API quota. If one model hits a 429, switching to another will work because they use separate rate limits.

Troubleshooting

Error Reference

Quota & Billing Errors (429)

These are the most common errors. There are two distinct 429 errors with different causes:

429: Quota exceeded for online_prediction_requests_per_base_model

What it means: You've hit the per-minute API call rate limit for a specific model.

Quick fix: Switch to a different model via the model parameter — each model has independent quota:

generate_image(prompt="...", model="gemini-3-pro-image")

Long-term fix: Request a quota increase:

1. Go to GCP Console → IAM & Admin → Quotas

2. Filter by online_prediction_requests_per_base_model

3. Find your model (e.g., gemini-3.1-flash-image or imagen-4.0-generate)

4. Click Edit Quotas → request a higher limit (default is often just 5 QPM)

429: Quota exceeded ... spending cap

What it means: You've hit a self-imposed billing spending limit, NOT an API rate limit.

Fix:

1. Go to GCP Console → Billing → Budgets & alerts

2. Find the budget with a spending cap

3. Increase or remove the cap

Tip: Prefer Gemini image models for new configurations. Imagen 4 generation IDs remain available for legacy Vertex AI setups but are scheduled for retirement on Aug 17, 2026.

Authentication Errors

Model Errors

Connection Errors

Prerequisites

• Python 3.10+

• uv — install with curl -LsSf https://astral.sh/uv/install.sh | sh

Local Development

git clone https://github.com/kevinten-ai/mcp-image-gen.git
cd mcp-image-gen

# Install dependencies (add --extra vertex for Vertex AI support)
uv sync

# Copy and configure environment variables
cp .env.example .env
# Edit .env with your API key

# Run the server directly
uv run image-gen

Debug with MCP Inspector

npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-image-gen run image-gen

Related Projects

• mcp-video-gen — Multi-provider AI video generation MCP server

• mcp-3d-gen — AI 3D model generation MCP server

License

MIT — see LICENSE for details.