mcp server

mcp-image-gen

Lightweight MCP server for AI image generation using Google Gemini. Supports Nano Banana 2, auto-save, and SOCKS proxy. Works with Claude Code, Cursor, and any MCP client.

kevinten-ai/mcp-image-gencommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`)

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcp-image-gen": {
      "command": "uvx",
      "args": [
        "gemini-image-gen"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 21, 2026

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

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:

API	Models	Endpoint	Request Format
Predict API	`imagen-4.0-*`	Vertex AI only	`instances[].prompt`
GenerateContent API	`gemini-*`	AI Studio + Vertex AI	`contents[].parts[].text`
Capability API	`imagen-3.0-capability-001`	Vertex AI only	`instances[].referenceImages[]` (edit)
Upscale API	`imagen-4.0-upscale-preview`	Vertex AI only	`instances[].image` (upscale)

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:

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

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:

Resource URI	Description
`guide://models`	Model comparison, pricing, quota tips, and selection guide
`guide://providers`	Provider setup, authentication, and troubleshooting

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

Variable	Required	Default	Description
`GEMINI_PROVIDER`	No	`ai-studio`	`ai-studio` or `vertex-ai`
`GEMINI_API_KEY`	Yes*	—	API key (AI Studio or GCP). *Not required if using ADC.
`GEMINI_MODEL`	No	`gemini-3.1-flash-image`	Default model (can be overridden per request via `model` parameter)
`IMAGE_OUTPUT_DIR`	No	`./output`	Directory to save generated images
`GCP_PROJECT_ID`	Vertex AI only	—	GCP project ID
`GCP_REGION`	No	`us-central1`	GCP region for Vertex AI

Supported Models

AI Studio (Gemini) — Free

Model ID	Quality	Speed	Pricing	Best for
`gemini-3.1-flash-image`	Highest	Fast	Free	Recommended default
`gemini-3-pro-image`	Highest	Slower	Free	Reasoning-enhanced composition
`gemini-2.5-flash-image`	Good	Fast	Free	Fallback

Vertex AI (Imagen) — GCP Credits

Model ID	Quality	Speed	Pricing	Best for
`gemini-3.1-flash-image`	Highest	Fast	Pay-per-use	Recommended default
`gemini-3-pro-image`	Highest	Slower	Pay-per-use	Reasoning-enhanced composition
`gemini-2.5-flash-image`	Good	Fast	Pay-per-use	Fallback
`imagen-4.0-generate-001`	High	Fast	~$0.04/image	Legacy Imagen; retires Aug 17, 2026
`imagen-4.0-ultra-generate-001`	Highest	Slower	~$0.06/image	Legacy Imagen; retires Aug 17, 2026
`imagen-4.0-fast-generate-001`	High	Fastest	~$0.02/image	Legacy Imagen; retires Aug 17, 2026

Vertex AI — Specialized Models

Model ID	Tool	Pricing	Notes
`imagen-3.0-capability-001`	`edit_image`	~$0.04/edit	Inpainting, outpainting, bg swap
`imagen-4.0-upscale-preview`	`upscale_image`	Preview	2x/4x super resolution

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

Error	Root Cause	Solution
`GEMINI_API_KEY is required`	Missing API key in env config	Set `GEMINI_API_KEY` in your MCP server env config
`GCP_PROJECT_ID is required`	Using Vertex AI without project ID	Set `GCP_PROJECT_ID` in your MCP server env config

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:

Go to GCP Console → IAM & Admin → Quotas
Filter by online_prediction_requests_per_base_model
Find your model (e.g., gemini-3.1-flash-image or imagen-4.0-generate)
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:

Go to GCP Console → Billing → Budgets & alerts
Find the budget with a spending cap
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

Error	Root Cause	Solution
`401 API keys not supported`	Model doesn't accept API key auth	Use ADC: run `gcloud auth application-default login`, remove `GEMINI_API_KEY`
`403 Permission denied`	API key lacks Vertex AI permissions	Enable Vertex AI API in GCP Console, or check API key restrictions
`Vertex AI auth failed`	No valid credentials found	Set `GEMINI_API_KEY` or run `gcloud auth application-default login`

Model Errors

Error	Root Cause	Solution
`404 model not found`	Wrong model ID for provider	AI Studio uses `gemini-`, Vertex AI supports both `imagen-` and `gemini-*`
`User location is not supported`	Regional restriction on model	Try a different region (`GCP_REGION`) or model such as `gemini-3.1-flash-image`
`No image generated`	Model declined or returned empty	Try a more descriptive prompt, avoid ambiguous or restricted content

Connection Errors

Error	Root Cause	Solution
`ConnectTimeout`	Network issue or proxy needed	If behind a firewall, configure SOCKS proxy via `httpx` env vars
`Failed to parse response`	Unexpected API response	Check model ID is correct, API may be temporarily down

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.