KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #ai-agent #developer-tools #claude-code #codex #deepseek-harness #ai-agents #react #mcp #rust

mcp-image-gen

★ 2 Open GitHub ↗

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.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Gemini Image Gen MCP Server

AI image generation, editing & upscaling via Google Gemini and Imagen. 
 Generate, edit (inpainting), and upscale images — all through one MCP server. 
 Works with Claude Code, Claude Desktop, Cursor, and any MCP-compatible client.

## 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**

<details>
<summary>Claude Code (CLI)</summary>

```bash
claude mcp add --transport stdio mcp-image \
 --env GEMINI_API_KEY=your_api_key \
 -- uv --directory /path/to/mcp-image-gen run image-gen
```
</details>

<details>
<summary>Claude Desktop / Cursor (JSON config)</summary>

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

**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](https://console.cloud.google.com/projectcreate))
- Vertex AI API enabled ([enable it](https://console.cloud.google.com/apis/library/aiplatform.googleapis.com))
- A GCP API key ([create one](https://console.cloud.google.com/apis/credentials))

**2. Install with Vertex AI support**

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

**3. Configure MCP**

<details>
<summary>Claude Code (CLI)</summary>

```bash
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
```
</details>

<details>
<summary>Claude Desktop / Cursor (JSON config)</summary>

```json
{
 "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"
 }
 }
 }
}
```
</details>

> **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:

```bash
# 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

```bash
--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:
1. Go to [GCP Console → IAM & Admin → Quotas](https://console.cloud.google.com/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](https://console.cloud.google.com/billing)
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

| 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](https://docs.astral.sh/uv/)** — install with `curl -LsSf https://astral.sh/uv/install.sh | sh`

## Local Development

```bash
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

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

## Related Projects

- [mcp-video-gen](https://github.com/kevinten-ai/mcp-video-gen) — Multi-provider AI video generation MCP server
- [mcp-3d-gen](https://github.com/kevinten-ai/mcp-3d-gen) — AI 3D model generation MCP server

## License

MIT — see [LICENSE](LICENSE) for details.

mcp-image-gen

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README