A production-ready Model Context Protocol (MCP) server that provides AI-powered image generation capabilities through Google's Gemini models with intelligent model selection.
⭐ NEW: Nano Banana 2 — Gemini 3.1 Flash Image! 🍌🚀
() is now the — delivering Pro-level quality at Flash speed:
AI image generation MCP server powered by Google Gemini, with smart model selection and 4K output
GEMINI_API_KEY, IMAGE_OUTPUT_DIR
上次检查
2026-11-05
星标
402
工具
—
可用率
—
Nano Banana 2
gemini-3.1-flash-image-preview
default model
🍌 Flash Speed + 4K Quality: Up to 3840px at Gemini 2.5 Flash latency
🌐 Google Search Grounding: Real-world knowledge for factually accurate images
🎯 Subject Consistency: Up to 5 characters and 14 objects per scene
✍️ Precision Text Rendering: Crystal-clear text placement in images
🏆 Gemini 3 Pro Image still available for maximum reasoning depth
✨ Features
🎨 Multi-Model AI Image Generation: Three Gemini models with intelligent automatic selection
🍌 Gemini 3.1 Flash Image (NB2): Default model — 4K resolution at Flash speed with grounding
🏆 Gemini 3 Pro Image: Maximum reasoning depth for the most complex compositions
⚡ Gemini 2.5 Flash Image: Legacy Flash model for high-volume rapid prototyping
🤖 Smart Model Selection: Automatically routes to NB2 or Pro based on your prompt
📐 Aspect Ratio Control ⭐ NEW: Specify output dimensions (1:1, 16:9, 9:16, 21:9, and more)
📋 Smart Templates: Pre-built prompt templates for photography, design, and editing
📁 File Management: Upload and manage files via Gemini Files API
🔍 Resource Discovery: Browse templates and file metadata through MCP resources
🛡️ Production Ready: Comprehensive error handling, logging, and validation
⚡ High Performance: Optimized architecture with intelligent caching
Option 1: From MCP Registry (Recommended)
This server is available in the Model Context Protocol Registry. Search for "nanobanana" or use the MCP name below with your MCP client.
Codex supports both the CLI and VSCode extension using the same config.toml. Once added, Codex can call generate_image, edit_image, and upload_file tools directly in your coding sessions.
Note: The Codex config file is shared by the CLI and the IDE extension. A TOML syntax error will break both simultaneously, so validate your edits carefully.
# Set environment variable
export GEMINI_API_KEY="your-gemini-api-key-here"
# Run server in stdio mode
uvx nanobanana-mcp-server@latest
# Or with pip installation
python -m nanobanana_mcp_server.server
🤖 Model Selection
Nano Banana supports three Gemini models with intelligent automatic selection:
# Automatic selection (recommended) — routes to NB2 by default
"A cat sitting on a windowsill" # → NB2 (default)
"Quick sketch of a cat" # → NB2 (speed keyword, NB2 is fast enough)
"Professional 4K product photo" # → Pro (strong quality keywords)
# Explicit NB2 selection
generate_image(
prompt="Product photo on white background",
model_tier="nb2", # Nano Banana 2 (Flash speed + 4K)
resolution="4k",
enable_grounding=True
)
# Leverage Nano Banana Pro for complex reasoning
generate_image(
prompt="Cinematic scene: three characters in a tense standoff at dusk",
model_tier="pro", # Pro for deep reasoning
resolution="4k",
thinking_level="HIGH", # Enhanced reasoning
enable_grounding=True
)
# Legacy Flash for high-volume drafts
generate_image(
prompt="Simple icon",
model_tier="flash" # Fast 1024px generation
)
# Control aspect ratio for different formats ⭐ NEW!
generate_image(
prompt="Cinematic landscape at sunset",
aspect_ratio="21:9" # Ultra-wide cinematic format
)
generate_image(
prompt="Instagram post about coffee",
aspect_ratio="1:1" # Square format for social media
)
generate_image(
prompt="YouTube thumbnail design",
aspect_ratio="16:9" # Standard video format
)
generate_image(
prompt="Mobile wallpaper of mountain vista",
aspect_ratio="9:16" # Portrait format for phones
)
📐 Aspect Ratio Control
Control the output image dimensions with the aspect_ratio parameter:
9:16 - Mobile portrait (phone wallpapers, stories)
21:9 - Ultra-wide cinematic
2:3, 3:2, 4:5, 5:4 - Various photo formats
# Examples for different use cases
generate_image(
prompt="Product showcase for e-commerce",
aspect_ratio="3:4", # Portrait format, good for product pages
model_tier="pro"
)
generate_image(
prompt="Social media banner for Facebook",
aspect_ratio="16:9" # Landscape banner format
)
Note: Aspect ratio works with both Flash and Pro models. For best results with specific aspect ratios at high resolution, use the Pro model with resolution="4k".
📁 Output Path Control ⭐ NEW!
Control where generated images are saved with the output_path parameter:
Three modes of operation:
Specific file path - Save to an exact file location:
IMAGE_OUTPUT_DIR is used only when output_path is omitted. A relative output_path such as images/sunset.png is resolved from the server process working directory, not from IMAGE_OUTPUT_DIR. ~/... expands to the home directory. A trailing slash selects directory mode even when that directory does not exist yet (outputs/), and the server creates it and generates the filename.
# Save to specific location with Pro model
generate_image(
prompt="Professional headshot",
model_tier="pro",
output_path="/Users/me/photos/headshot.png"
)
# Save multiple images to a directory
generate_image(
prompt="Product variations",
n=4,
output_path="/path/to/products/" # Each gets unique filename
)
⚙️ Environment Variables
Configuration options:
# Authentication (Required)
# Method 1: API Key
GEMINI_API_KEY=your-gemini-api-key-here
# Method 2: Vertex AI (Google Cloud)
NANOBANANA_AUTH_METHOD=vertex_ai
GCP_PROJECT_ID=your-project-id
GCP_REGION=global # Required for gemini-3-pro-image-preview and NB2; use "us-central1" only for legacy 2.5 Flash Image
# Model Selection (optional)
NANOBANANA_MODEL=auto # Options: flash, nb2, pro, auto (default: auto → nb2)
# Optional
IMAGE_OUTPUT_DIR=/path/to/image/directory # Default: ~/nanobanana-images
GEMINI_BASE_URL=https://custom-api.example.com # Custom API endpoint (for proxies/gateways)
LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR
LOG_FORMAT=standard # standard, json, detailed
🐛 Troubleshooting
Common Issues
"GEMINI_API_KEY not set"
Add your API key to the MCP server configuration in your client