nanobanana-mcp-image-generation

# Nano Banana MCP Image Generation > Skill by [ara.so](https://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 1. **Google Gemini API Key**: Get one free at https://makersuite.google.com/app/apikey 2. 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): ```json { "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: ```json { "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`: ```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`: ```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: ```json { "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:** ```python # 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:** ```python # 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:** ```python # 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:** ```python # 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:** ```python 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 ```python 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 ```python 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 ```python 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: ```python # 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 ```python # 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 ```python # 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(