gemini-image-mcp

# gemini-image-mcp

A simple, focused MCP server for Google Gemini's native image generation — the "Nano Banana" models. Generate, edit, and locally process images from Claude Code, Claude Desktop, or any stdio-based MCP client. Two tools, no bloat.

Built for agents: a single call returns a *saved image* — or, with one-call background removal, a ready-to-use transparent PNG — without streaming image data through your agent's context. Uses Gemini's `generateContent` API (not the deprecated Imagen API).

## Install

```bash
npm install -g @jimothy-snicket/gemini-image-mcp
```

Or use directly with npx:

```bash
npx -y @jimothy-snicket/gemini-image-mcp
```

**Claude Code (one command):**

```bash
claude mcp add gemini-image -- npx -y @jimothy-snicket/gemini-image-mcp
```

Requires a `GEMINI_API_KEY` environment variable — see [Setup](#setup) for details.

**Set up a config file (optional):**

```bash
npx @jimothy-snicket/gemini-image-mcp --init
```

Creates `~/.gemini-image-mcp.json` with commented defaults. For project-specific overrides:

```bash
npx @jimothy-snicket/gemini-image-mcp --init --local
```

## Features

### generate_image — AI-powered
- **Text-to-image** — describe what you want, get an image
- **Image editing** — provide reference images and an editing instruction
- **Video-to-image** — the model *watches* a video and synthesizes a new image from what it understood: YouTube thumbnails, posters from footage, summary infographics, style-transferred stills. See [Advanced Features](#advanced-features)
- **Thinking depth control** — `thinkingLevel: "HIGH"` for renders that depend on reasoning (infographics, diagrams, dense typography); cheap `MINIMAL` default otherwise
- **Transparent assets in one call** — `removeBackground` returns a clean transparent PNG: a local AI matte (works on any subject; optional add-on, see below) by default, or built-in green-screen / white-threshold keying. No extra API cost
- **Multi-turn edits** — pass a `sessionId` to refine an image across calls, with prior turns kept as context
- **Multi-image input** — reference images for editing and character/style consistency (per-model limits; the API enforces)
- **Cost reporting** — every response includes token counts, estimated USD cost, and session totals
- **Rate limiting** — configurable per-hour caps on requests and cost to prevent runaway agents
- **Auto model discovery** — detects available image models from your API key at startup
- **Seed** — reproducible generation with integer seeds
- **Search grounding** — ground renders in live Google Search results; `"web+image"` also pulls image-search results for mood boards and trend references, with sources returned for attribution. See [Advanced Features](#advanced-features)

### process_image — Local (free, no API calls)
- **Crop** — pixel-exact, aspect ratio (center), or focal point (attention/entropy)
- **Resize** — to width, height, or both (maintains aspect ratio)
- **Background removal** — threshold-based (white backgrounds) or chroma key (green screen, any solid colour)
- **Chroma key pipeline** — HSV keying with smoothstep feather, spill suppression, and edge anti-aliasing
- **Trim** — auto-remove whitespace borders
- **Format conversion** — PNG, JPEG, WebP with quality control

### Both tools
- **Output organization** — meaningful filenames with auto-versioning, subfolders
- **Generation manifest** — `generations.jsonl` logs every generation with prompt, params, cost
- **Full aspect ratio support** — 1:1, 16:9, 9:16, 3:2, 2:3, 4:3, 3:4, 21:9
- **Resolution control** — 1K, 2K, 4K

## Setup

### 1. Get a Gemini API Key

Go to [Google AI Studio](https://aistudio.google.com/apikey) and create an API key.

> **Billing required:** image generation has **no free tier** — free-tier keys get `429 RESOURCE_EXHAUSTED` (quota limit 0) on every image model. Enable pay-as-you-go billing on the key's Google Cloud project ([usage & billing](https://ai.dev/rate-limit)). Images cost ~$0.03–$0.24 each depending on model and resolution; the cheapest model (`gemini-3.1-flash-lite-image`, the default) is ~$0.034 per image.

### 2. Set the API Key

The server reads your key from the `GEMINI_API_KEY` environment variable. Set it once so it's available in every session:

**Windows (PowerShell — run as admin):**
```powershell
[System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'your-key-here', 'User')
```
Then restart your terminal.

**macOS / Linux:**
```bash
echo 'export GEMINI_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc
```
(Use `~/.zshrc` if you're on zsh.)

**Verify it's set:**
```bash
echo $GEMINI_API_KEY
```

### 3. Connect to Your MCP Client

Pick the method that matches how you use MCP:

#### Claude Code (one-liner)

```bash
claude mcp add gemini-image -- npx -y @jimothy-snicket/gemini-image-mcp
```

Claude Code will pick up `GEMINI_API_KEY` from your environment automatically.

#### Claude Code (manual `.mcp.json`)

Add to `.mcp.json` in your project root or `~/.claude/.mcp.json` for global access:

```json
{
  "mcpServers": {
    "gemini-image": {
      "command": "npx",
      "args": ["-y", "@jimothy-snicket/gemini-image-mcp"],
      "env": {
        "GEMINI_API_KEY": "${GEMINI_API_KEY}"
      }
    }
  }
}
```

The `${GEMINI_API_KEY}` syntax reads the value from your shell environment — your actual key never gets written into config files.

#### Claude Desktop

Edit `claude_desktop_config.json`:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "gemini-image": {
      "command": "npx",
      "args": ["-y", "@jimothy-snicket/gemini-image-mcp"],
      "env": {
        "GEMINI_API_KEY": "${GEMINI_API_KEY}"
      }
    }
  }
}
```

Restart Claude Desktop after saving.

#### Other MCP Clients

Any client that supports stdio transport works. Point it at `npx -y @jimothy-snicket/gemini-image-mcp` and pass `GEMINI_API_KEY` in the environment.

### Security Notes

- Never commit your API key to version control. The `${GEMINI_API_KEY}` syntax in config files references your environment — the key itself stays in your shell profile.
- If your `.mcp.json` is in a project repo, add it to `.gitignore` or use the global config at `~/.claude/.mcp.json` instead.
- For extra security, you can use a wrapper script that reads the key from your OS keychain (macOS Keychain, Windows Credential Manager) and launches the server with it injected.

## Configuration

All optional. The only required setup is `GEMINI_API_KEY` (covered above).

| Variable | Default | Description |
|----------|---------|-------------|
| `OUTPUT_DIR` | `~/gemini-images` | Default directory for saved images |
| `DEFAULT_MODEL` | `gemini-3.1-flash-lite-image` | Default Gemini model |
| `LOG_LEVEL` | `info` | `debug`, `info`, or `error` |
| `REQUEST_TIMEOUT_MS` | `60000` | API request timeout in milliseconds |
| `MAX_REQUESTS_PER_HOUR` | `0` (unlimited) | Max image generations per rolling hour |
| `MAX_COST_PER_HOUR` | `0` (unlimited) | Max estimated cost (USD) per rolling hour |
| `SESSION_TIMEOUT_MS` | `1800000` (30min) | Multi-turn session expiry |
| `GEMINI_IMAGE_AUTO_INSTALL` | `1` (on) | Auto-install the AI matte engine on first `removeBackground: { mode: "auto" }` use. Set `0` to disable (then `auto` falls back to chroma/threshold with instructions) |

Set these the same way as `GEMINI_API_KEY`, or pass them in the `env` block of your MCP config.

**Rate limiting** is recommended when agents have access to this tool. An agent in a loop can generate images quickly — set `MAX_REQUESTS_PER_HOUR=20` and `MAX_COST_PER_HOUR=5` as sensible defaults.

### Config File

Instead of environment variables, you can use a JSON config file. Create one with:

```bash
npx @jimothy-snicket/gemini-image-mcp --init
```

This creates `~/.gemini-image-mcp.json` with all defaults and inline documentation. Edit it to set your preferences.

**Priority:** env vars > local config (`.gemini-image-mcp.json` in CWD) > global config (`~/.gemini-image-mcp.json`) > defaults.

You can also set per-tool defaults so every request uses your preferred settings:

```json
{
  "defaultModel": "gemini-3.1-flash-image",
  "defaults": {
    "generate": {
      "aspectRatio": "16:9",
      "resolution": "2K"
    },
    "process": {
      "removeBackground": { "color": "#00FF00" },
      "trim": true
    }
  }
}
```

Per-request parameters always override config defaults.

**Custom pricing.** Cost estimates come from a built-in per-token rate table (there's no pricing API to fetch live). If you use a model the table doesn't know yet — or Google changes a rate before this package updates — add `pricingOverrides` so cost reporting stays accurate without waiting for a release:

```json
{
  "pricingOverrides": {
    "some-new-image-model": {
      "inputPerMillion": 0.5,
      "textOutputPerMillion": 60,
      "imageOutputPerMillion": 60,
      "thinkingPerMillion": 60
    }
  }
}
```

Models with no entry (built-in or override) still generate — their cost is reported as `unknown` rather than guessed.

## Tool: `generate_image`

### Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `prompt` | Yes | Text description or editing instruction |
| `images` | No | Array of file paths to input/reference images |
| `model` | No | Gemini model ID |
| `aspectRatio` | No | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`, plus `1:4`, `4:1`, `1:8`, `8:1` (gemini-3.1-flash-image). Validated by the API. |
| `resolution` | No | `512` (gemini-3.1-flash-image only), `1K`, `2K`, `4K` |
| `outputDir` | No | Override output directory for this request |
| `filename` | No | Base name for saved file (e.g. `hero-banner`). Auto-versioned if duplicate. |
| `subfolder` | No | Subfolder within output directory (e.g. `landing-page`) |
| `sessionId` | No | Continue a multi-turn editing session fro