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.
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.
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
Create a key at Google AI Studio.
git clone https://github.com/petrkindlmann/nano-banana-mcp.git
cd nano-banana-mcp
npm installclaude mcp add nano-banana --scope user \
--env GEMINI_API_KEY=your_key_here \
-- node /absolute/path/to/nano-banana-mcp/index.jsAdd 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.
Env var | Required | Description |
| ✅ | Your Gemini API key. |
| — | 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, aspect ratios, grounding) regardless of the ID you assign it.
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.
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). |
Tier | Model ID | Sizes | Search grounding | Thinking | Video input | JPEG output |
|
| 1K | — | — | — | — (PNG only) |
|
| 0.5K, 1K, 2K, 4K | web + 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_storydefaults topro(best interleaved quality);generate_from_videois locked toflash(the only tier that accepts video).
generate_imageArg | 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_imageSame 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_storyArg | 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_setArg | Type | Default | Notes |
| string[] | — | Required. One prompt per icon. |
| string | — | Required. Files are named after each prompt ( |
|
|
| |
|
|
|
generate_from_videoArg | Type | Default | Notes |
| string | — | Required. Public YouTube URL. |
| string | — | Required. What to generate from the video. |
| string | — | Required. Output file path. |
| string |
| |
|
|
| |
| boolean |
|
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.
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.
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, helpers
lib/gemini.js — API client, retries, response extraction, previews
lib/tools.js — tool schemas and handlers
index.js — MCP server wiring
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.
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | 1K | |
| model | No | nano=1K fast, flash=default/4K, pro=professional/4K/thinking | flash |
| ratio | No | Aspect ratio for the output | 1:1 |
| output | Yes | Output file path; extension picks the format (.png or .jpg; jpg needs flash/pro) | |
| prompt | Yes | Edit instruction, e.g. 'Change the background to sunset, keep everything else identical' | |
| preview | No | Return a small preview image | |
| use_search | No | Ground the edit with Google Search | |
| show_thinking | No | Include thought summaries (pro) | |
| reference_images | No | Paths to reference images on disk (max 14; flash: 10 object + 4 character, pro: 6 + 5) | |
| previous_interaction_id | No | ID from a previous generate_image/edit_image call to continue from |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses behavioral traits: returns a new interaction_id for iteration, limits for reference_images (up to 14, with model-specific constraints), and that the output format is determined by file extension. It does not mention destructive behavior but editing images typically implies modification.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise and well-structured. It front-loads the core purpose, then explains two distinct usage modes, and ends with a prompt tip. Every sentence adds value, though it could be slightly tighter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters and no output schema, the description covers key behaviors: iteration flow, reference image limits, and prompt style. It could mention that output size defaults to 1K and model defaults to flash, but these are in the schema. Overall, it provides sufficient context for an agent to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 90%, so baseline is 3. The description adds meaning beyond schema by explaining the recommended workflow (previous_interaction_id) and specific use cases for reference_images. It also provides a prompt tip that enhances understanding of how to craft effective prompts.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Edit or iterate on an image with a follow-up prompt,' clearly stating the core function. It distinguishes from siblings like generate_image (which likely generates from scratch) by emphasizing iterative editing and providing specific use cases like virtual try-on and product placement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use each mode: use previous_interaction_id for multi-turn editing (recommended) or reference_images for specific tasks. It also includes a prompt tip. However, it does not explicitly state when not to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | 1K | |
| ratio | No | 16:9 | |
| output | Yes | Output file path; extension picks the format | |
| prompt | Yes | What to generate, e.g. 'Create a poster capturing the key themes' | |
| preview | No | Return a small preview image | |
| youtube_url | Yes | Public YouTube video URL |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the 'flash model only' constraint and lists output types, but lacks details on authentication needs, rate limits, resource consumption, or what happens with different video lengths.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences provide essential information: the core function, constraint, and example outputs, with no redundant or verbose content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given six parameters and no output schema, the description is somewhat sparse. It does not explain parameter interactions, output format, or best practices for complex video-to-image generation, leaving gaps for an agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, so the description adds minimal parameter insight beyond the schema. It reinforces that youtube_url must be public but does not clarify size, ratio, or prompt formatting beyond schema defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates an image from a YouTube video URL, with specific examples like thumbnails, posters, infographics, and key-moment art, differentiating it from sibling tools like generate_image which likely handle general image generation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies the tool works only with public YouTube URLs and the flash model, providing clear context. However, it does not explicitly state when not to use it or recommend alternative tools for other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | 1K | |
| model | No | flash | |
| prompts | Yes | Icon prompts, one per icon | |
| output_dir | Yes | Directory to save icons |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behavioral trait: sequential chaining for style consistency. Also specifies file naming pattern. With no annotations, it covers essential generative behavior, though lacks details on failure handling or determinism.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with clear front-loading: main behavior, naming rule, then use cases. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core behavior (style consistency, naming) and use cases. Lacks detail on parameter effects, error handling, and output format (assumed images). Reasonably complete for a simple tool with 4 parameters and no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% with descriptions only for prompts and output_dir. Description adds naming convention (icon-shopping-cart.png) but doesn't explain size options (0.5K to 4K) or model differences (nano/flash/pro). Moderate added value beyond schema enums.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Strong verb 'Generate' and resource 'set of style-consistent icons' clearly defined. Distinguishes from siblings like generate_image by emphasizing multi-turn chaining for consistency. Specific file naming convention and use cases provided.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage contexts (app icon sets, UI glyphs, feature illustrations) but no explicit when-to-use vs alternatives like generate_image. No exclusion criteria or prerequisites stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | Output resolution; 0.5K flash only | 1K |
| model | No | nano=1K fast, flash=default/4K, pro=professional/4K/thinking | flash |
| ratio | No | Aspect ratio, e.g. 16:9, 1:1, 9:16, 4:3; 21:9/1:4/4:1/1:8/8:1 flash only | 1:1 |
| output | Yes | Output file path; extension picks the format (.png or .jpg; jpg needs flash/pro), e.g. generated/hero.jpg | |
| prompt | Yes | Image generation prompt | |
| preview | No | Return a small preview image so the client can see the result | |
| use_search | No | Ground with Google Search for real-time info (flash/pro) | |
| show_thinking | No | Include the model's thought summaries in the response (pro) | |
| use_image_search | No | Also ground with Google Image Search as visual context (flash only) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses model behavior differences, output format dependency on file extension, interaction_id for iteration, and search grounding. It does not cover failure modes or authentication, but key behavioral aspects are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is front-loaded with purpose and model overview. It uses bullet-like sentences for clarity. Some redundancy (e.g., repeating model capabilities in both first sentence and parameter list) could be trimmed, but overall efficient for the amount of information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers models, output, search, and preview. However, no output schema exists, and the description does not detail the full return value (e.g., whether image is returned as URL or base64, or the structure of interaction_id). The preview parameter is mentioned but response format incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, giving baseline 3. The description adds value by explaining model nuances (nano=fast/1K, flash=best/4K, pro=professional/thinking), output format selection via extension, and search capability. Prompt tips further enhance parameter understanding beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Generate a single image' with specific model names (Nano Banana) and explicitly lists use cases (illustrations, product photography, etc.). It differentiates this tool from siblings like edit_image and generate_icon_set by focusing on single image generation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use each model (nano for fast, flash for best all-around, pro for professional) and when to enable search. However, it does not explicitly state when not to use this tool (e.g., for generating multiple images at once), though sibling names imply alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | Optional image resolution (omit to let the model decide) | |
| model | No | pro gives the best interleaved quality | pro |
| ratio | No | Optional aspect ratio for the images (omit to let the model decide) | |
| prompt | Yes | What to create, e.g. 'A 6-panel storyboard of a fox learning to fly, illustrations interleaved with captions' | |
| basename | No | Filename prefix for saved images | story |
| output_dir | Yes | Directory to save the images |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description provides key behavioral details: saves numbered images to a directory and returns markdown with inline image paths. This adds value beyond the schema, though it omits potential side effects like overwriting files.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently convey the core function, examples, output format, and side effect. No redundancy; front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description explains the return value (markdown with image paths) and side effect (saved images). It lacks details on image count or ordering but is adequate for typical usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds example values for prompt but does not elaborate on other parameters beyond the schema. Overall, marginal added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates interleaved text and images from a single prompt, listing specific use cases like storyboards and comics. This distinguishes it from sibling tools that handle single images or icons.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through examples but does not explicitly state when to use this tool versus alternatives or provide exclusions. Sibling context is absent from the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.1.0edit_imagegenerate_from_videogenerate_icon_setgenerate_imagegenerate_storyScored 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.
Generate marketing images, videos and audios for campaigns, product content, and brand assets.
Generate images, videos, voiceovers, and captions from a chat prompt.
Generate and edit images, videos, and audio with 150+ models from 20+ vendors.
Generate and edit images and create short videos inside Claude. Prepaid credits, no subscription.
