Nano Banana MCP Image Generation

Skill by ara.so — MCP Skills collection.

Overview

Nano Banana is a production-ready MCP server that provides AI-powered image generation through Google's Gemini models. It features intelligent automatic model selection between three tiers (Flash, NB2, and Pro), 4K output, aspect ratio control, smart templates, and file management.

Key Features:

🍌 Gemini 3.1 Flash Image (NB2): Default model — 4K resolution at Flash speed with Google Search grounding
🏆 Gemini 3 Pro Image: Maximum reasoning depth for complex compositions
⚡ Gemini 2.5 Flash Image: Legacy high-speed model for rapid prototyping
🤖 Smart Auto Selection: Automatically routes to the best model based on your prompt
📐 Aspect Ratio Control: 1:1, 16:9, 9:16, 21:9, and more
📋 Smart Templates: Pre-built prompts for photography, design, and editing
📁 File Management: Upload and reference images via Gemini Files API

Installation

Prerequisites

Google Gemini API Key: Get one free at https://makersuite.google.com/app/apikey
Set environment variable: GEMINI_API_KEY=your-api-key-here

MCP Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "nanobanana": {
      "command": "uvx",
      "args": ["nanobanana-mcp-server@latest"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

Cursor

Add to Cursor's MCP configuration:

{
  "mcpServers": {
    "nanobanana": {
      "command": "uvx",
      "args": ["nanobanana-mcp-server@latest"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

Codex (OpenAI)

Add to ~/.codex/config.toml:

[mcp_servers.nanobanana]
command = "uvx"
args = ["nanobanana-mcp-server@latest"]

[mcp_servers.nanobanana.env]
GEMINI_API_KEY = "your-gemini-api-key-here"

Continue.dev

Add to config.json:

{
  "mcpServers": [
    {
      "name": "nanobanana",
      "command": "uvx",
      "args": ["nanobanana-mcp-server@latest"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  ]
}

Vertex AI Authentication (Google Cloud)

For production deployments on Google Cloud, use Application Default Credentials:

{
  "mcpServers": {
    "nanobanana": {
      "command": "uvx",
      "args": ["nanobanana-mcp-server@latest"],
      "env": {
        "NANOBANANA_AUTH_METHOD": "vertex_ai",
        "GCP_PROJECT_ID": "your-project-id",
        "GCP_REGION": "global"
      }
    }
  }
}

Prerequisites for Vertex AI:

Enable Vertex AI API: gcloud services enable aiplatform.googleapis.com
Grant IAM role: roles/aiplatform.user

Core MCP Tools

1. `generate_image` - Generate Images from Text

The primary tool for creating images from text prompts.

Parameters:

prompt (required): Text description of the image to generate
model_tier (optional): "auto" (default), "nb2", "pro", or "flash"
resolution (optional): "4k" (3840px, default for pro/nb2) or "1k" (1024px)
aspect_ratio (optional): "1:1", "16:9", "9:16", "21:9", "4:3", "3:4", etc.
n (optional): Number of images to generate (1-4, default 1)
thinking_level (optional): "LOW" or "HIGH" (Pro model only)
enable_grounding (optional): Enable Google Search grounding (boolean)
output_path (optional): Custom save path for generated images
negative_prompt (optional): Elements to avoid in the image
use_template (optional): Template ID (e.g., "product_photo", "portrait")
seed (optional): Integer for reproducible generation

Basic Usage:

# Simple image generation (auto selects NB2 by default)
generate_image(
    prompt="A serene mountain landscape at sunset with a lake reflection"
)

# Generate with specific aspect ratio
generate_image(
    prompt="Modern minimalist product photo of a coffee mug",
    aspect_ratio="4:3"
)

# Generate multiple variations
generate_image(
    prompt="Abstract geometric pattern in blue and gold",
    n=3
)

Advanced Usage:

# High-quality 4K generation with NB2 (default)
generate_image(
    prompt="Professional product photography of a luxury watch on marble surface",
    model_tier="nb2",
    resolution="4k",
    aspect_ratio="16:9",
    enable_grounding=True
)

# Maximum quality with Pro model
generate_image(
    prompt="Cinematic scene: three characters in a tense standoff at dusk, dramatic lighting",
    model_tier="pro",
    resolution="4k",
    thinking_level="HIGH",
    enable_grounding=True,
    negative_prompt="blurry, low quality, distorted faces"
)

# Fast generation with Flash model
generate_image(
    prompt="Simple icon design for a mobile app",
    model_tier="flash",
    n=4
)

# Custom output path
generate_image(
    prompt="Logo design for tech startup",
    output_path="/path/to/output/logo.png",
    aspect_ratio="1:1"
)

# Reproducible generation with seed
generate_image(
    prompt="Fantasy castle in the clouds",
    seed=42,
    aspect_ratio="16:9"
)

2. `edit_image` - Edit Existing Images

Edit or modify existing images with text prompts.

Parameters:

image_path (required): Path to the input image file
prompt (required): Description of the desired edit
model_tier (optional): "auto", "nb2", "pro", or "flash"
mask_path (optional): Path to a mask image (white = edit region)
resolution (optional): "4k" or "1k"
output_path (optional): Custom save path

Usage Examples:

# Basic image editing
edit_image(
    image_path="/path/to/photo.jpg",
    prompt="Add a sunset sky in the background"
)

# Masked editing (inpainting)
edit_image(
    image_path="/path/to/portrait.jpg",
    prompt="Change the shirt color to blue",
    mask_path="/path/to/mask.png",
    model_tier="pro"
)

# High-quality editing with Pro model
edit_image(
    image_path="/path/to/landscape.jpg",
    prompt="Add dramatic storm clouds and rain",
    model_tier="pro",
    resolution="4k",
    output_path="/path/to/edited.jpg"
)

3. `upload_file` - Upload Images for Reference

Upload images to Gemini Files API for use in generation or editing.

Parameters:

file_path (required): Path to the image file to upload
display_name (optional): Friendly name for the file

Usage:

# Upload a reference image
upload_file(
    file_path="/path/to/reference.jpg",
    display_name="product_reference"
)

# Upload multiple references
upload_file(file_path="/path/to/style1.jpg", display_name="style_example_1")
upload_file(file_path="/path/to/style2.jpg", display_name="style_example_2")

Then reference in generation:

generate_image(
    prompt="Create a similar product photo in the same style",
    # The uploaded files are automatically available to the model context
    model_tier="pro"
)

Model Selection Guide

🍌 Nano Banana 2 (NB2) - Default Model

When to use:

Default choice for most use cases
Production-ready 4K output needed
Text rendering in images
Subject consistency (multiple characters/objects)
Real-world accuracy (with grounding enabled)

Specs:

Speed: ~2-4 seconds
Resolution: Up to 4K (3840px)
Special: Google Search grounding, subject consistency, text rendering

generate_image(
    prompt="Instagram post with text overlay: 'Summer Sale 50% Off'",
    model_tier="nb2",
    resolution="4k",
    aspect_ratio="1:1",
    enable_grounding=True
)

🏆 Pro Model - Maximum Quality

When to use:

Complex narrative scenes
Maximum reasoning required
Multiple characters with intricate interactions
When prompt contains: "4K", "professional", "production", "cinematic"

Specs:

Speed: ~5-8 seconds
Resolution: Up to 4K (3840px)
Special: Advanced reasoning, configurable thinking levels

generate_image(
    prompt="Cinematic establishing shot: a dystopian city with three distinct districts visible, neon lights reflecting on wet streets, flying vehicles in the distance",
    model_tier="pro",
    resolution="4k",
    thinking_level="HIGH",
    enable_grounding=True
)

⚡ Flash Model - High Speed

When to use:

High-volume generation (batches)
Quick drafts and iterations
1024px resolution is sufficient
When prompt contains: "quick", "draft", "sketch"

Specs:

Speed: ~2-3 seconds
Resolution: Up to 1024px
Special: Fastest generation

generate_image(
    prompt="Quick sketch of a user interface mockup",
    model_tier="flash",
    n=4  # Generate 4 variations quickly
)

🤖 Auto Mode (Recommended)

Let the system intelligently select the best model:

# Auto routes to NB2 by default
generate_image(prompt="A cat sitting on a windowsill")

# Auto routes to Pro for quality keywords
generate_image(prompt="Professional 4K product photography of a watch")

# Auto routes to NB2 for speed keywords (NB2 is fast enough)
generate_image(prompt="Quick product thumbnail", n=3)

Smart Templates

Access pre-built prompt templates via use_template parameter.

Available Templates

Photography Templates:

product_photo: Clean product photography on white background
portrait: Professional portrait photography with natural lighting
landscape: Scenic landscape photography with depth
food: Appetizing food photography with natural lighting

Design Templates:

logo: Modern, minimalist logo design
illustration: Digital illustration with vibrant colors
abstract: Abstract art with geometric patterns
icon: Simple, clean icon design

Editing Templates:

background_replace: Replace image background while keeping subject
style_transfer: Apply artistic style to existing image
enhance: Enhance image quality and details

Using Templates

# Product photography template
generate_image(
    prompt="wireless headphones",
    use_template="product_photo",
    aspect_ratio="1:1"
)

# Portrait template
generate_image(
    prompt="female executive, confident expression",
    use_template="portrait",
    resolution="4k"
)

# Logo design template
generate_image(
    prompt="tech startup focusing on AI, modern and clean",
    use_template="logo",
    aspect_ratio="1:1"
)

# Background replacement template
edit_image(
    image_path="/path/to/portrait.jpg",
    prompt="office environment with natural light",
    use_template="background_replace",
    model_tier="pro"
)

Common Patterns

Pattern 1: Social Media Content Generation

# Instagram post (square)
generate_image(
    prompt="Motivational quote background: 'Dream Big' in elegant typography, pastel gradient",
    model_tier="nb2",
    aspect_ratio="1:1",
    resolution="4k"
)

# YouTube thumbnail (16:9)
generate_image(
    prompt="Eye-catching thumbnail: person with shocked expression, bright colors, text 'You Won't Believe This!'",
    model_tier="nb2",
    aspect_ratio="16:9",
    enable_grounding=True
)

# Story/Reel (9:16)
generate_image(
    prompt="Vertical video background: animated gradient with floating geometric shapes",
    aspect_ratio="9:16",
    resolution="4k"
)

Pattern 2: Product Photography Workflow

# Step 1: Generate base product image
generate_image(
    prompt="Modern wireless earbuds on marble surface, studio lighting, professional product photography",
    model_tier="nb2",
    resolution="4k",
    aspect_ratio="4:3",
    output_path="/products/earbuds_base.jpg"
)

# Step 2: Generate variations with different angles
generate_image(
    prompt="Same wireless earbuds, 45-degree angle, spotlight from top right",
    model_tier="nb2",
    resolution="4k",
    n=3
)

# Step 3: Edit to add lifestyle context
edit_image(
    image_path="/products/earbuds_base.jpg",
    prompt="Add lifestyle context: gym environment in blurred background",
    model_tier="pro"
)

Pattern 3: Iterative Design Refinement

# Start with fast iterations
generate_image(
    prompt="Logo concept for coffee shop, minimalist",
    model_tier="flash",
    n=4,
    aspect_ratio="1:1"
)

# Refine selected concept with NB2
generate_image(
    prompt="Coffee shop logo: simplified coffee cup icon with steam forming 'C' letter, earth tones",
    model_tier="nb2",
    resolution="4k",
    seed=12345  # Use seed from preferred flash result
)

# Final high-quality version with Pro
generate_image(
    prompt="Final coffee shop logo: refined coffee cup with elegant steam detail, warm brown and cream colors, professional branding quality",
    model_tier="pro",
    resolution="4k",
    aspect_ratio="1:1"
)

Pattern 4: Multi-Image Campaign

# Generate consistent style across multiple images
base_prompt = "e-commerce product photography, white background, soft shadows, professional lighting"

# Image 1: Hero shot
generate_image(
    prompt=f"{base_prompt}, luxury watch close-up, central composition",
    model_tier="nb2",
    resolution="4k",
    aspect_ratio="16:9",
    seed=100
)

# Image 2: Detail shot
generate_image(
    prompt=f"{base_prompt}, same luxury watch, focus on crown and dial details",
    model_tier="nb2",
    resolution="4k",
    seed=100  # Same seed for consistency
)

# Image 3: Lifestyle context
generate_image(
    prompt=f"{base_prompt}, same luxury watch on wrist, business attire visible",
    model_tier="pro",  # Pro for complex composition
    resolution="4k",
    seed=100
)

Pattern 5: Image Editing Pipeline

# Upload original image
upload_file(
    file_path="/raw/photo.jpg",
    display_name="original_photo"
)

# Edit 1: Color correction
edit_image(
    image_path="/raw/photo.jpg",
    prompt="Enhance colors, increase saturation slightly, professional color grading",
    output_path="/edited/step1_color.jpg"
)

# Edit 2: Background replacement
edit_image(
    image_path="/edited/step1_color.jpg",
    prompt="Replace background with modern office interior, maintain subject lighting",
    use_template="background_replace",
    model_tier="pro",
    output_path="/edited/step2_background.jpg"
)

# Edit 3: Final touches
edit_image(
    image_path="/edited/step2_background.jpg",
    prompt="Add subtle vignette, enhance sharpness, professional portrait finish",
    model_tier="pro",
    resolution="4k",
    output_path="/edited/final.jpg"
)

Aspect Ratio Quick Reference

Ratio	Use Case	Example
`1:1`	Instagram posts, profile pics	Social media content
`4:3`	Classic photography	Product shots, portraits
`3:4`	Portrait orientation	Magazine covers
`16:9`	Widescreen, YouTube	Thumbnails, presentations
`9:16`	Mobile portrait	Phone wallpapers, Stories
`21:9`	Ultra-wide cinematic	Movie-style scenes
`2:3`	Photo print standard	Traditional prints
`3:2`	DSLR camera standard	Professional photography

Troubleshooting

Issue: "API Key not found"

Solution:

# Verify environment variable is set
echo $GEMINI_API_KEY

# For Claude Desktop, check config file has the key
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

Issue: "Model not available in region"

Solution:

NB2 and Pro models require GCP_REGION=global
Legacy Flash model uses us-central1

{
  "env": {
    "NANOBANANA_AUTH_METHOD": "vertex_ai",
    "GCP_PROJECT_ID": "your-project",
    "GCP_REGION": "global"
  }
}

Issue: Low-quality results

Solution:

# Use Pro model with high thinking level
generate_image(
    prompt="[your prompt] - photorealistic, high detail, professional quality",
    model_tier="pro",
    resolution="4k",
    thinking_level="HIGH",
    negative_prompt="blurry, low quality, distorted, artificial"
)

Issue: Inconsistent style across generations

Solution:

# Use seed for reproducibility
generate_image(
    prompt="Your prompt here",
    seed=42,  # Same seed = similar style
    model_tier="nb2"
)

# Or enable grounding for factual consistency
generate_image(
    prompt="Your prompt here",
    enable_grounding=True,
    model_tier="nb2"
)

Issue: File upload fails

Solution:

# Check file exists and is readable
import os
assert os.path.isfile("/path/to/image.jpg"), "File not found"

# Supported formats: JPEG, PNG, GIF, WebP
# Max size: 20MB per file

upload_file(
    file_path="/path/to/image.jpg",
    display_name="my_reference"
)

Issue: Generation timeout

Solution:

Pro model can take 5-8 seconds
Use NB2 for faster results (2-4 seconds)
Use Flash for maximum speed (2-3 seconds)

# If Pro times out, try NB2
generate_image(
    prompt="Your complex prompt",
    model_tier="nb2",  # Faster than Pro
    resolution="4k"    # Still 4K quality
)

Advanced Configuration

Custom Output Directory

import os

# Set custom output path for all generations
OUTPUT_DIR = "/path/to/my/images"
os.makedirs(OUTPUT_DIR, exist_ok=True)

generate_image(
    prompt="Landscape photo",
    output_path=f"{OUTPUT_DIR}/landscape_001.jpg"
)

Batch Processing with Error Handling

prompts = [
    "Modern office interior",
    "Coastal sunset landscape",
    "Abstract geometric pattern"
]

for i, prompt in enumerate(prompts):
    try:
        generate_image(
            prompt=prompt,
            output_path=f"/batch/image_{i:03d}.jpg",
            model_tier="nb2",
            resolution="4k"
        )
    except Exception as e:
        print(f"Failed to generate image {i}: {e}")
        continue

Environment Variables Reference

# Required (choose one authentication method)
GEMINI_API_KEY=your-api-key-here

# OR for Vertex AI
NANOBANANA_AUTH_METHOD=vertex_ai
GCP_PROJECT_ID=your-project-id
GCP_REGION=global

# Optional
NANOBANANA_LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR
NANOBANANA_OUTPUT_DIR=/custom/output/path

Best Practices

Use Auto Mode by default - Let the system select the best model
Specify aspect ratios - Better results than cropping after generation
Enable grounding for realism - Use enable_grounding=True for real-world accuracy
Use templates - Save time with pre-optimized prompts
Iterate from Flash to Pro - Start fast, refine with quality
Set seeds for consistency - Reproducible results across generations
Use negative prompts - Explicitly exclude unwanted elements
Leverage Pro's thinking - Set thinking_level="HIGH" for complex scenes
Batch similar tasks - Generate variations with n parameter
Upload references - Use upload_file for style/subject consistency

Resources

API Key: https://makersuite.google.com/app/apikey
MCP Registry: https://registry.modelcontextprotocol.io/?q=nanobanana
GitHub: https://github.com/zhongweili/nanobanana-mcp-server
Gemini Models: https://ai.google.dev/models/gemini

nanobanana-mcp-image-generation

Nano Banana MCP Image Generation

Overview

Installation

Prerequisites

MCP Client Configuration

Claude Desktop

Cursor

Codex (OpenAI)

Continue.dev

Vertex AI Authentication (Google Cloud)

Core MCP Tools

1. generate_image - Generate Images from Text

2. edit_image - Edit Existing Images

3. upload_file - Upload Images for Reference

Model Selection Guide

🍌 Nano Banana 2 (NB2) - Default Model

🏆 Pro Model - Maximum Quality

⚡ Flash Model - High Speed

🤖 Auto Mode (Recommended)

Smart Templates

Available Templates

Using Templates

Common Patterns

Pattern 1: Social Media Content Generation

Pattern 2: Product Photography Workflow

Pattern 3: Iterative Design Refinement

Pattern 4: Multi-Image Campaign

Pattern 5: Image Editing Pipeline

Aspect Ratio Quick Reference

Troubleshooting

Issue: "API Key not found"

Issue: "Model not available in region"

Issue: Low-quality results

Issue: Inconsistent style across generations

Issue: File upload fails

Issue: Generation timeout

Advanced Configuration

Custom Output Directory

Batch Processing with Error Handling

Environment Variables Reference

Best Practices

Resources

1. `generate_image` - Generate Images from Text

2. `edit_image` - Edit Existing Images

3. `upload_file` - Upload Images for Reference