nano-banana-mcp

A Model Context Protocol server for AI image generation and editing with Google's Gemini "Nano Banana" image models, via the Interactions API.

Generate, edit, and iterate on images directly from Claude Code, Claude Desktop, Cursor, or any MCP-compatible client — with multi-turn editing, search grounding, interleaved storyboards, style-consistent icon sets, and image-from-video.

<p align="center"> <img src="docs/images/showcase-product.jpg" width="32%" alt="Photorealistic product shot of a teal ceramic coffee mug" /> <img src="docs/images/showcase-isometric.jpg" width="32%" alt="Isometric illustration of a developer workstation" /> <img src="docs/images/showcase-sticker.png" width="32%" alt="Kawaii banana sticker wearing sunglasses" /> </p> <p align="center"><em>All generated by this server — a photoreal product shot, an isometric illustration with legible text, and a vector sticker. No edits.</em></p>

Note: This server uses the Gemini Interactions API, which is currently in beta. The Gemini 3 image models (gemini-3-pro-image, gemini-3.1-flash-image) may require access on your API key. The nano tier (gemini-2.5-flash-image) is the most widely available. See Requirements.

Features

• Text-to-image — high-quality images from a prompt, up to 4K, with aspect-ratio and resolution control
• Multi-turn editing — iterate conversationally; each result returns an interaction_id you pass back to keep editing
• Reference images — up to 14 inputs for virtual try-on, product placement, compositing, style transfer, photo restoration, attribute replacement, 2D→3D mockups
• Search grounding — ground images in real-time data (weather, news, scores) with Google Search and Google Image Search
• Interleaved stories — one prompt → a sequence of captioned images (storyboards, comics, recipes, illustrated explainers)
• Style-consistent icon sets — chained generation keeps a uniform look across an icon set
• Image from video — generate thumbnails/posters from a public YouTube URL
• Inline previews — downscaled previews returned to the client so the model can see what it generated and self-correct
• Robust — automatic retries with backoff on rate limits and transient errors; clear, actionable error messages

Quick Start

1. Get a Gemini API key

Create a key at Google AI Studio.

2. Install

git clone https://github.com/petrkindlmann/nano-banana-mcp.git
cd nano-banana-mcp
npm install

3. Register with your MCP client

Claude Code

claude mcp add nano-banana --scope user \
  --env GEMINI_API_KEY=your_key_here \
  -- node /absolute/path/to/nano-banana-mcp/index.js

Claude Desktop / Cursor / Windsurf / VS Code

Add to your MCP config (e.g. ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "nano-banana": {
      "command": "node",
      "args": ["/absolute/path/to/nano-banana-mcp/index.js"],
      "env": {
        "GEMINI_API_KEY": "your_key_here"
      }
    }
  }
}

Restart your client. The five tools below will appear.

Configuration

Env var	Required	Description
GEMINI_API_KEY	✅	Your Gemini API key.
NANO_BANANA_MODEL_NANO	—	Override the nano tier's model ID.
NANO_BANANA_MODEL_FLASH	—	Override the flash tier's model ID.
NANO_BANANA_MODEL_PRO	—	Override the pro tier's model ID.

The model IDs are beta/preview models that Google rotates and occasionally retires. If a newer version ships — or a configured ID is deprecated — point a tier at a new model without editing code:

"env": {
  "GEMINI_API_KEY": "your_key_here",
  "NANO_BANANA_MODEL_FLASH": "gemini-3.2-flash-image"
}

Each tier keeps its capability profile (sizes, aspect ratios, grounding) regardless of the ID you assign it.

Usage

Just ask in natural language — your MCP client picks the right tool and arguments.

You: Generate a 16:9 hero image of a misty pine forest at dawn, cinematic, save it to hero.jpg

Claude: calls generate_image → saves hero.jpg, returns an interaction_id and a preview

You: Make the fog heavier and add a deer in the clearing

Claude: calls edit_image with the previous interaction_id → hero-v2.jpg

Multi-turn editing is the recommended way to iterate: each result carries an interaction_id, and passing it back keeps the full conversation context so edits stay consistent.

Tools

Tool	Description
generate_image	Generate a single image from a text prompt. Optional search grounding, thinking, and aspect/size control.
edit_image	Edit or iterate on an image — chain via previous_interaction_id, or pass reference images from disk.
generate_story	Generate interleaved text + images from one prompt (storyboards, comics, recipes, explainers).
generate_icon_set	Generate a set of style-consistent icons via chained generation.
generate_from_video	Generate an image from a public YouTube video URL (flash model only).

Models

Tier	Model ID	Sizes	Search grounding	Thinking	Video input	JPEG output
nano	gemini-2.5-flash-image	1K	—	—	—	— (PNG only)
flash	gemini-3.1-flash-image	0.5K, 1K, 2K, 4K	web + image	—	✅	✅
pro	gemini-3-pro-image	1K, 2K, 4K	web	✅	—	✅

Which should I use?

• flash (default) — your go-to. Best all-around balance of quality, cost, and latency. Up to 4K, search grounding, the widest aspect ratios (21:9, 1:4, etc.), and the only tier that accepts video input.
• pro — the highest-quality renderer. Use for professional/deliverable assets, complex multi-element instructions, and legible text rendered inside the image (infographics, posters, menus). A built-in "Thinking" pass refines composition before rendering. Slower and pricier.
• nano — speed and volume. 1K-only, no grounding/thinking, always returns PNG. Reach for it when generating many images fast and per-image quality matters less.

generate_story defaults to pro (best interleaved quality); generate_from_video is locked to flash (the only tier that accepts video).

generate_image

Arg	Type	Default	Notes
prompt	string	—	Required. What to generate.
output	string	—	Required. Output file path. Extension picks the format: .png (default) or .jpg (flash/pro only — nano always returns PNG).
model	nano/flash/pro	flash	Model tier.
ratio	string	1:1	e.g. 16:9, 9:16, 4:3; 21:9/1:4/4:1/1:8/8:1 are flash-only.
size	0.5K/1K/2K/4K	1K	0.5K is flash-only.
use_search	boolean	false	Ground with Google Search (flash/pro).
use_image_search	boolean	false	Also use Google Image Search as visual context (flash).
show_thinking	boolean	false	Include the model's thought summaries (pro).
preview	boolean	true	Return a small preview image to the client.

Returns the file path and an interaction_id — pass it to edit_image to keep iterating.

edit_image

Same image controls as generate_image, plus:

Arg	Type	Notes
previous_interaction_id	string	Continue a previous generation/edit conversationally (the recommended way to iterate).
reference_images	string[]	Paths to reference images on disk (max 14; flash: 10 object + 4 character, pro: 6 + 5).

generate_story

Arg	Type	Default	Notes
prompt	string	—	Required. e.g. "A 6-panel storyboard of a fox learning to fly, illustrations interleaved with captions."
output_dir	string	—	Required. Directory for the numbered images.
basename	string	story	Filename prefix.
model	nano/flash/pro	pro	pro gives the best interleaved quality.
ratio / size	string	—	Optional; omit to let the model decide.

generate_icon_set

Arg	Type	Default	Notes
prompts	string[]	—	Required. One prompt per icon.
output_dir	string	—	Required. Files are named after each prompt (icon-shopping-cart.png).
model	nano/flash/pro	flash
size	0.5K/1K/2K/4K	1K

generate_from_video

Arg	Type	Default	Notes
youtube_url	string	—	Required. Public YouTube URL.
prompt	string	—	Required. What to generate from the video.
output	string	—	Required. Output file path.
ratio	string	16:9
size	0.5K/1K/2K/4K	1K
preview	boolean	true

Prompt tips

For best results, write full sentences describing subject + setting + lighting + camera/lens + mood — narrative beats keyword soup.

A photorealistic close-up portrait of an elderly Japanese ceramicist with deep wrinkles and a warm smile. Soft golden-hour light streaming through a window. Captured with an 85mm portrait lens, soft bokeh background. Serene and masterful mood.

Requirements

• Node.js 18+ (uses the built-in node:test runner and modern ES modules)
• A Gemini API key (GEMINI_API_KEY)
• The Interactions API is beta; Gemini 3 image tiers (flash, pro) may require access. The nano tier is the most widely available — set model: "nano" if flash/pro are unavailable on your key.

Development

npm test          # unit tests (node:test) — no API key needed
npm run smoke     # live smoke test — requires GEMINI_API_KEY

The codebase is split into focused modules:

• lib/config.js — model tables, aspect-ratio/size validation, helpers
• lib/gemini.js — API client, retries, response extraction, previews
• lib/tools.js — tool schemas and handlers
• index.js — MCP server wiring

License

MIT