Gemini Image

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
• 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
• 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

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.

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

[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.

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.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).

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:

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:

{

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

{

"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

Example Response

{

"imagePath": "/home/user/gemini-images/hero-banner.png", "mimeType": "image/png", "model": "gemini-3.1-flash-lite-image", "sessionId": "session-1711929600000-a1b2c3", "sessionTurn": 1, "usage": { "promptTokens": 5, "outputTokens": 1295, "imageTokens": 1290, "thinkingTokens": 412, "totalTokens": 1712, "estimatedCost": "$0.0390", "pricingVerifiedDate": "2026-09-16" }, "session": { "generationsThisSession": 3, "totalCostThisSession": "$0.1161", "generationsThisHour": 5, "limit": { "maxPerHour": 20, "maxCostPerHour": 5, "remainingThisHour": 15 } } }

Usage Examples

Text-to-image:

"Generate a hero image for a SaaS landing page, modern gradient style, 16:9"

Image editing:

"Take this screenshot and redesign the header with a dark theme" (with image paths)

Iterative editing (multi-turn):

Generate an image, then call again with the returned sessionId and a refinement like "make it more minimal" — the prior image stays in context.

Organized output:

"Generate a hero banner" with `f