nano-banana-mcp
nano-banana-mcp is an MCP server that lets you generate and edit AI images with Google's Gemini "Nano Banana" models directly from any MCP-compatible client.
Text-to-image generation — create images from a prompt at up to 4K, with control over aspect ratio (14 supported, e.g. 16:9, 1:1, 21:9) and resolution (0.5K–4K).
Multi-turn editing — iterate conversationally by passing the returned
interaction_idback toedit_imageto keep context and consistency.Reference-image editing — pass up to 14 images from disk for virtual try-on, product placement, compositing, style transfer, photo restoration, attribute replacement, or 2D→3D mockups.
Search grounding — ground generations in real-time data via Google Search (flash/pro) and Google Image Search (flash).
Interleaved stories — generate captioned image sequences like storyboards, comics, recipes, and illustrated explainers.
Style-consistent icon sets — produce chained icons that share a uniform look (app icons, UI glyphs, feature illustrations).
Image from video — generate thumbnails, posters, or key-moment art from a public YouTube URL (flash only).
Inline previews — return small previews so the client model can see and self-correct its output.
Model tiers — choose
nano(fast, 1K),flash(default, up to 4K, video input), orpro(highest quality, thinking, 4K).Robustness — automatic retries with backoff and clear error messages.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@nano-banana-mcp Generate a photorealistic product shot of a teal ceramic coffee mug."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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. Thenanotier (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_idyou pass back to keep editingReference 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
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 install3. 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.jsClaude 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 |
| ✅ | Your Gemini API key. |
| — | Override the |
| — | Override the |
| — | Override the |
| — | Override the |
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, 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.jpgClaude: calls
generate_image→ saveshero.jpg, returns aninteraction_idand a previewYou: Make the fog heavier and add a deer in the clearing
Claude: calls
edit_imagewith the previousinteraction_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 a single image from a text prompt. Optional search grounding, thinking, and aspect/size control. |
| Edit or iterate on an image — chain via |
| Generate interleaved text + images from one prompt (storyboards, comics, recipes, explainers). |
| Generate a set of style-consistent icons via chained generation. |
| Generate an image from a public YouTube video URL (flash model only). |
Models
Tier | Model ID | Sizes | Search grounding | Thinking | Video input |
|
| 512, 1K | — | — | — |
|
| 1K | — | — | — |
|
| 512, 1K, 2K, 4K | web + image | — | ✅ |
|
| 512, 1K, 2K, 4K | web | ✅ | — |
Every tier accepts all 14 aspect ratios (1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4,
9:16, 16:9, 21:9, 1:4, 4:1, 1:8, 8:1). Output files always match their
extension (.png, .jpg, .webp): the API returns JPEG (PNG for nano), and the
server converts locally when the extension asks for something else.
Which should I use?
flash(default) — your go-to. Best all-around balance of quality, cost, and latency. Up to 4K, web + image search grounding, 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.lite— speed and volume. Nano Banana 2 Lite: Google's fastest, cheapest image model. 1K max, no grounding. Reach for it when generating many images fast — drafts, thumbnails, quick local edits.nano— the original Nano Banana. 1K-only, no grounding/thinking. The most widely available tier if your key lacks Gemini 3 access.
generate_storydefaults topro(best interleaved quality);generate_from_videois locked toflash(the only tier that accepts video).
generate_image
Arg | Type | Default | Notes |
| string | — | Required. What to generate. |
| string | — | Required. Output file path. Extension picks the format: |
|
|
| Model tier. |
| string |
| e.g. |
|
|
|
|
| boolean |
| Ground with Google Search (flash/pro). |
| boolean |
| Also use Google Image Search as visual context (flash). |
| boolean |
| Include the model's thought summaries (pro). |
| boolean |
| 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 |
| string | Continue a previous generation/edit conversationally (the recommended way to iterate). |
| string[] | Paths to reference images on disk (max 14; flash: 10 object + 4 character, pro: 6 + 5). |
generate_story
Arg | Type | Default | Notes |
| string | — | Required. e.g. "A 6-panel storyboard of a fox learning to fly, illustrations interleaved with captions." |
| string | — | Required. Directory for the numbered images. |
| string |
| Filename prefix. |
|
|
|
|
| string | — | Optional; omit to let the model decide. |
generate_icon_set
Arg | Type | Default | Notes |
| string[] | — | Required. One prompt per icon. |
| string | — | Required. Files are named after each prompt ( |
|
|
| |
|
|
|
generate_from_video
Arg | Type | Default | Notes |
| string | — | Required. Public YouTube URL. |
| string | — | Required. What to generate from the video. |
| string | — | Required. Output file path. |
| string |
| |
|
|
| |
| boolean |
|
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 20.9+ (required by
@google/genaiandsharp)A Gemini API key (
GEMINI_API_KEY)The Interactions API is beta; Gemini 3 image tiers (
flash,pro) may require access. Thenanotier is the most widely available — setmodel: "nano"ifflash/proare unavailable on your key.
Development
npm test # unit tests (node:test) — no API key needed
npm run smoke # live smoke test — requires GEMINI_API_KEYThe codebase is split into focused modules:
lib/config.js— model tables, aspect-ratio/size validation, helperslib/gemini.js— API client, retries, response extraction, previewslib/tools.js— tool schemas and handlersindex.js— MCP server wiring
License
Available Tools
5 toolsedit_imageA
Edit or iterate on an image with a follow-up prompt. Pass previous_interaction_id from a prior generate_image/edit_image call for conversational multi-turn editing (recommended way to iterate). Or pass reference_images from disk (up to 14) for: virtual try-on, product placement in scenes, combining/compositing images, style transfer, photo restoration, attribute replacement (colors/materials), 2D-to-3D mockups. Returns a new interaction_id for further iteration. Prompt tip: describe subject + setting + lighting + camera/lens + mood in full sentences; narrative beats keyword soup.
Inputs: output (required), prompt (required), size, model, +6 more.
generate_from_videoA
Generate an image from a public YouTube video URL (flash model only). Analyzes the video and generates an image from it — thumbnails, posters, infographics, key-moment art.
Inputs: output (required), prompt (required), youtube_url (required), size, +2 more.
generate_icon_setA
Generate a set of style-consistent icons via multi-turn interactions — each icon chains off the previous to keep the same visual style. Files are named after each prompt (icon-shopping-cart.png). Use for app icon sets, UI glyphs, feature illustrations.
Inputs: prompts (required), output_dir (required), size, model.
generate_imageA
Generate a single image with Nano Banana (Gemini image models). Models: nano=fast/1K, flash=best all-around/up to 4K (default), pro=professional/4K/thinking/grounding. Use cases: illustrations, product photography, logos, posters, photorealistic scenes, stickers, mockups. Output format follows the file extension: .png (default) or .jpg (flash/pro only — nano always returns PNG). Set use_search to ground in real-time data (weather, news, scores). Returns interaction_id — pass it to edit_image to iterate. Prompt tip: describe subject + setting + lighting + camera/lens + mood in full sentences; narrative beats keyword soup.
Inputs: output (required), prompt (required), size, model, +5 more.
generate_storyA
Generate interleaved text + images from one prompt: storyboards, comics, recipes with step photos, illustrated explainers, tutorials. Saves numbered images to a directory and returns the narrative as markdown with image paths inline.
Inputs: prompt (required), output_dir (required), size, model, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct image generation or editing task: single image generation, iterative editing, icon set creation, video-based generation, and story generation. No two tools overlap in functionality.
All tool names follow a consistent 'verb_noun' pattern (e.g., generate_image, edit_image, generate_icon_set). The naming is predictable and matches the tool's purpose.
With 5 tools, the set covers the core image generation and editing workflows without being overly broad or too narrow. Each tool serves a clear, non-redundant purpose.
The tool surface covers all essential operations: generating images from scratch, editing/iterating, creating icon sets, generating from video, and producing multi-image stories. No obvious missing functionality for the stated domain.
Maintenance
Related MCP Connectors
Commercially licensed image generation and editing with IP indemnification.
Generate, extend and edit AI images and videos, then assemble clips on a timeline and render.
Create images, video and audio; reuse assets and build Canvas workflows from your AI assistant.
Image generation, image editing and text/image-to-video with credit quotes and connection budgets.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables AI image generation, editing, and composition using Google's Gemini image models (Nano Banana Pro and Nano Banana). Supports text-to-image generation, multi-image composition, flexible aspect ratios, high-resolution output up to 4K, and real-time information grounding.4-
- FlicenseNot gradedqualityCmaintenanceEnables image generation and editing using Google's Gemini models with support for model selection and custom aspect ratios. Users can generate high-quality images or modify existing ones through natural language prompts while controlling specific parameters like quality and dimensions.-
- AlicenseAqualityCmaintenanceEnables AI image generation and editing using Google's Gemini Multimodal Image APIs.61MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI-powered image generation and editing using Gemini and Imagen models, supporting text-to-image, image editing, and multi-image composition through MCP tools.MIT