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

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
• 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 — up to ~14 reference images on gemini-3.1-flash-image (~11 on gemini-3-pro-image)
• 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 the gemini-3.x image models

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 (manua

... View full README on GitHub