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.

All generated by this server — a photoreal product shot, an isometric illustration with legible text, and a vector sticker. No edits.

> 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

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

Models

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`

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:

`generate_story`

`generate_icon_set`

`generate_from_video`

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