gemini-image-mcp

MCP server for Google Gemini image generation, editing, and processing. Two tools, no bloat.

Built on Gemini's native image generation API (generateContent), not the deprecated Imagen API. If you're migrating from Imagen (shutting down June 2026), this is what you move to — multi-turn editing, reference images, and all the features Imagen didn't have.

Install

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

Or use directly with npx:

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

Claude Code (one command):

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

Requires a GEMINI_API_KEY environment variable — see Setup for details.

Set up a config file (optional):

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

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

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
• Multi-turn sessions — iteratively refine images with conversation history
• Multi-image input — up to 14 reference images on gemini-3-pro
• 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
• Google Search grounding — real-world accuracy on gemini-3.1-flash

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 and create an API key. It's free to start with generous rate limits.

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

[System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'your-key-here', 'User')

Then restart your terminal.

macOS / Linux:

echo 'export GEMINI_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc

(Use ~/.zshrc if you're on zsh.)

Verify it's set:

echo $GEMINI_API_KEY

3. Connect to Your MCP Client

Pick the method that matches how you use MCP:

Claude Code (one-liner)

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:

{
  "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.

... View full README on GitHub