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.

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

Related MCP server: Nano Banana MCP Server

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