An MCP server that provides image generation and editing capabilities
Nano Banana MCP Server
An MCP server that provides image generation and editing capabilities. It exposes AI-powered image generation via Googleβs Gemini models, including intelligent model selection. The repository is production-ready and includes support for Nano Banana 2 with a default Gemini model configuration.
π οΈ Key Features
Provides image generation and editing capabilities
Uses Google Gemini models for AI-powered image generation
Includes intelligent model selection
Nano Banana 2 is the default model (gemini-3.1-flash-image-preview)
π Use Cases
Generate images using Gemini-based AI capabilities
Edit or modify images using MCP-provided image editing support
β‘ Developer Benefits
Use a production-ready MCP server for Gemini-based image generation
Default to Nano Banana 2 (gemini-3.1-flash-image-preview) for Flash-speed performance
β οΈ Limitations
Server description only specifies image generation/editing; no other MCP tools are detailed here
A production-ready Model Context Protocol (MCP) server that provides AI-powered image generation capabilities through Google's Gemini models with intelligent model selection.
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 variableexport 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
python
# 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.
python
# 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:
bash
# 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
Ensure you're using the latest version: uvx nanobanana-mcp-server@latest
Check that your client supports MCP (Claude Desktop 0.10.0+)
"Permission denied" errors
The server creates images in ~/nanobanana-images by default
Ensure write permissions to your home directory
Development Setup
For local development:
bash
# Clone repository
git clone https://github.com/zhongweili/nanobanana-mcp-server.git
cd nanobanana-mcp-server
# Install with uv
uv sync# Set environmentexport GEMINI_API_KEY=your-api-key-here
# Run locally
uv run python -m nanobanana_mcp_server.server