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 API (not the deprecated Imagen API).
Google Gemini image generation, editing, and local processing via MCP
GEMINI_API_KEY
ตรวจสอบล่าสุด
2026-11-09
ดาว
—
เครื่องมือ
—
อัปไทม์
—
generateContent
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:
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
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:
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:
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:
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:
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 from a previous response
seed
No
Integer seed for reproducible generation
grounding
No
"web" = Google Search grounding; "web+image" adds image-search results (gemini-3.1-flash-image only). See Advanced Features
useSearchGrounding
No
Legacy alias for grounding: "web"
thinkingLevel
No
"MINIMAL" (default) or "HIGH" — thinking depth on the gemini-3.1-flash family. See Advanced Features
videos
No
Array of file paths to input videos for video-to-image (gemini-3.1-flash family). See Advanced Features
removeBackground
No
Return a transparent PNG cutout. { "mode": "auto" } = local AI matte (any subject; default); { "mode": "chroma" } = green screen; { "mode": "threshold" } = white removal (line art). No extra API cost
"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 filename: "hero", subfolder: "landing-page" → saves to ~/gemini-images/landing-page/hero.png
High quality:
"A photorealistic product shot of headphones on marble, 4K" (using gemini-3-pro-image)
Transparent asset (one call):
"A glossy red sneaker, product shot" with removeBackground: { "mode": "auto" } → a ready-to-place transparent PNG. The local AI matte works on any subject — no green screen needed.
Tool: process_image
Local image processing via sharp. Free, fast, no API calls.
Parameters
Parameter
Required
Description
imagePath
Yes
Path to the image file to process
crop
No
Crop by pixel dimensions, aspect ratio, or focal point strategy
resize
No
Resize to width/height (maintains aspect ratio)
removeBackground
No
Remove background: { "mode": "auto" } (AI matte, any subject), { "mode": "chroma" } (green screen), or { "mode": "threshold" } (white). Defaults to chroma if color set, else threshold
trim
No
Auto-remove whitespace/transparent borders
format
No
Convert to png, jpeg, or webp
quality
No
Output quality for JPEG/WebP (1-100)
filename
No
Base name for saved file. Auto-versioned if duplicate.
subfolder
No
Subfolder within output directory
outputDir
No
Override output directory
Crop Options
// Pixel-exact
{"width": 500, "height": 300, "left": 100, "top": 50}
// Aspect ratio (center crop)
{"aspectRatio": "16:9"}
// Focal point — shifts crop to the most interesting region
{"aspectRatio": "16:9", "strategy": "attention"}
// Detail-based — shifts crop to the most detailed region
{"aspectRatio": "16:9", "strategy": "entropy"}
Background Removal Options
// AI semantic matte — best quality, works on ANY subject
{"mode": "auto"}
// White/light background (threshold)
{"mode": "threshold", "threshold": 240}
// Green screen (chroma key)
{"mode": "chroma", "color": "#00FF00"}
// Any solid colour
{"mode": "chroma", "color": "#0000FF", "tolerance": 60}
mode: "auto" runs a local BiRefNet matte that isolates the subject semantically — so it handles hair, glass, and green/yellow subjects that chroma key can't. The matte engine isn't bundled (keeps the base install ~65 MB). On your first auto call the server auto-installs it (@huggingface/transformers, ~340 MB) plus the fp16 model (~109 MB) — a one-time pause of a minute or two, then it runs locally with no extra API cost. Set GEMINI_IMAGE_AUTO_INSTALL=0 to disable auto-install (then auto falls back to returning the image with instructions to install it manually). chroma and threshold need nothing extra.
Chroma key (mode: "chroma") uses HSV keying with smoothstep feathering, spill suppression, and 5-pass edge anti-aliasing (default tolerance 80). Use #00FF00 for AI-generated green screens — it works better than matching the exact shade Gemini produces.
Note: Chroma key destroys subjects that share the key colour (green/yellow) and transparent/reflective subjects (glass) — the green parrot vanishes. For those, use mode: "auto" (the AI matte preserves them), or the canvas approach: feed a solid-colour background image to generate_image and let Gemini place the subject with correct lighting. The canvas approach is still best for truly transparent objects like glass, which should transmit the final background rather than be cut out.
Common Pipelines
Subject on a specific background (canvas approach):
generate_image → "Place a [subject] on this background" with images: [solid colour canvas]
One API call. Best for yellow, green, or glass subjects where chroma key struggles.
Transparent asset (one call):
generate_image → "A product photo of <subject>" with removeBackground: {mode: "auto"}
One API call → a transparent PNG. The local AI matte works on any subject. (For truly transparent/reflective objects like glass, the canvas approach above is still best.)
Transparent asset from green screen (zero-dependency):
generate_image → "A product photo on a bright green background"
process_image → removeBackground {mode: "chroma"} + trim
Avoids the matte model entirely — best for high-contrast subjects on locked-down/offline machines.
These are opt-in knobs on generate_image. Most requests don't need them — they're documented here rather than in the tool schema to keep agent context small.
Video-to-image (videos)
The model watches your video and synthesizes a new image from what it understood — the subject, mood, colors, and action — rather than copying a frame. If you just want a frame, use ffmpeg; this is for images that require understanding the footage:
YouTube thumbnails — "watch my video and make a click-worthy thumbnail" (the headline use case: no scrubbing for a non-blurry frame)
Posters and cover art — gameplay footage → key art, a gig recording → gig poster, a product demo → a clean product shot
Summary infographics — "diagram the key steps from this tutorial video"
Style-transferred stills — a pencil-sketch of a dance video, a comic panel from home footage
{
"prompt": "A bold movie poster for this video, dramatic typography",
"videos": ["./clip.mp4"],
"model": "gemini-3.1-flash-image"
}
Supported on the gemini-3.1-flash family (gemini-3.1-flash-image, gemini-3.1-flash-lite-image); other models reject it.
Accepts local files (mp4, mov, webm, avi, mpeg, wmv, flv, 3gpp), max 500MB each, up to 3 per call. Each video is uploaded to Google's Files API, polled until processed, used for the call, then deleted. Video tokens count as input (a 2s clip ≈ 140 tokens).
Not combinable with sessionId — sessions are text+image only, and video turns don't create sessions (the upload is deleted after the call, so a stored session would replay a dead reference).
Upload + server-side processing happen before the generation call and are bounded by a 120s-per-video processing cap, not by REQUEST_TIMEOUT_MS (which only bounds the generation call itself).
You must have the necessary rights to any video you upload.
Scope note: this is video input. Video generation is a different model family (Google's Veo, accessed via its own API) and is out of this server's scope.
Thinking depth (thinkingLevel)
All Gemini 3 image models "think" before rendering. The default MINIMAL keeps cost and latency down. Use "HIGH" for renders where quality depends on reasoning: infographics, diagrams, menus, dense typography, multi-step compositions.
{ "prompt": "An infographic explaining the water cycle with labeled diagrams", "thinkingLevel": "HIGH" }
Supported on the gemini-3.1-flash family (API validates elsewhere). Can be set as a project default via defaults.generate.thinkingLevel in the config file.
Image-search grounding (grounding: "web+image")
grounding: "web" grounds the render in live Google Search results (weather, stock charts, current events). "web+image" — exclusive to gemini-3.1-flash-image — also pulls in image-search results, useful for mood boards and trend references.
When grounding is used, the response includes a grounding object: source chunks (URI + title, up to 5), searchQueries, and searchEntryPointHtml. Google's Terms of Service require displaying the search suggestions entry point when you show grounded results — pass searchEntryPointHtml through to the user (it is render-ready HTML provided by Google for exactly this purpose).
Not supported on gemini-3.1-flash-lite-image (the API rejects grounding there).
Models
Model
Strengths
Resolution
Notes
gemini-3.1-flash-lite-image
Cheapest (~$0.034/image), video input
1K
Default (Nano Banana 2 Lite). No search grounding; up to 14 reference images but not optimized for multi-image or multi-turn editing — prefer 3.1-flash for those
gemini-3.1-flash-image
Speed + quality, search grounding (web + image), video input
512, 1K, 2K, 4K
~$0.07/1K image. Up to 10 object + 4 character + 3 style reference images
gemini-3-pro-image
Best quality, text rendering
1K, 2K, 4K
~$0.13/1K image. Up to 6 object + 5 character reference images
gemini-2.5-flash-image
Legacy
1K
Shuts down 2026-10-02
The retired -preview IDs (gemini-3-pro-image-preview, gemini-3.1-flash-image-preview) may still appear in your key's model list but were retired 2026-06-25 — use the GA IDs above. The server discovers whichever image models your API key supports at startup and validates each request against that live list, so new models work without an update.
Development
bun install
bun run build # TypeScript -> dist/
bun run dev # Run directly with Bun