๐ Nano Banana MCP Server ๐
A production-ready Model Context Protocol (MCP) server that offers AI-powered image generation capabilities through Google's Gemini models with intelligent model selection. It enables users to generate high - quality images efficiently, catering to various needs from rapid prototyping to professional production.
โญ NEW: Gemini 3 Pro Image Support! ๐
Now featuring Nano Banana Pro - Google's latest and most powerful image generation model:
- ๐ Professional 4K Quality: Generate stunning images up to 3840px resolution.
- ๐ Google Search Grounding: Access real - world knowledge for factually accurate images.
- ๐ง Advanced Reasoning: Configurable thinking levels for complex compositions.
- ๐ฏ Superior Text Rendering: Crystal - clear text in images at high resolution.
- ๐จ Enhanced Understanding: Better context comprehension for complex prompts.
โจ Features
- ๐จ Multi - Model AI Image Generation: Intelligent selection between Flash (speed) and Pro (quality) models.
- โก Gemini 2.5 Flash Image: Fast generation (1024px) for rapid prototyping.
- ๐ Gemini 3 Pro Image: High - quality up to 4K with Google Search grounding.
- ๐ค Smart Model Selection: Automatically chooses the optimal model 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.
๐ Quick Start
Prerequisites
- Google Gemini API Key - Get one free here.
- Python 3.11+ (for development only).
Installation
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.
mcp - name: io.github.zhongweili/nanobanana - mcp - server
Option 2: Using uvx
uvx nanobanana-mcp-server@latest
Option 3: Using pip
pip install nanobanana-mcp-server
๐ง Configuration
Authentication Methods
Nano Banana supports two authentication methods via NANOBANANA_AUTH_METHOD:
- API Key (
api_key): Uses GEMINI_API_KEY. Best for local development and simple deployments.
- Vertex AI ADC (
vertex_ai): Uses Google Cloud Application Default Credentials. Best for production on Google Cloud (Cloud Run, GKE, GCE).
- Automatic (
auto): Defaults to API Key if present, otherwise tries Vertex AI.
1. API Key Authentication (Default)
Set GEMINI_API_KEY environment variable.
2. Vertex AI Authentication (Google Cloud)
Required environment variables:
NANOBANANA_AUTH_METHOD=vertex_ai (or auto)
GCP_PROJECT_ID=your-project-id
GCP_REGION=us-central1 (default)
Prerequisites:
- Enable Vertex AI API:
gcloud services enable aiplatform.googleapis.com
- Grant IAM Role:
roles/aiplatform.user to the service account.
Claude Desktop
Option 1: Using Published Server (Recommended)
Add to your claude_desktop_config.json:
{
"mcpServers": {
"nanobanana": {
"command": "uvx",
"args": ["nanobanana-mcp-server@latest"],
"env": {
"GEMINI_API_KEY": "your-gemini-api-key-here"
}
}
}
}
Option 2: Using Local Source (Development)
If you are running from source code, point to your local installation:
{
"mcpServers": {
"nanobanana-local": {
"command": "uv",
"args": [
"run",
"python",
"-m",
"nanobanana_mcp_server.server"
],
"cwd": "/absolute/path/to/nanobanana-mcp-server",
"env": {
"GEMINI_API_KEY": "your-gemini-api-key-here"
}
}
}
}
Option 3: Using Vertex AI (ADC)
To authenticate with Google Cloud Application Default Credentials (instead of an API Key):
{
"mcpServers": {
"nanobanana-adc": {
"command": "uvx",
"args": ["nanobanana-mcp-server@latest"],
"env": {
"NANOBANANA_AUTH_METHOD": "vertex_ai",
"GCP_PROJECT_ID": "your-project-id",
"GCP_REGION": "us-central1"
}
}
}
}
Configuration file locations:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
Claude Code (VS Code Extension)
Install and configure in VS Code:
- Install the Claude Code extension.
- Open Command Palette (
Cmd/Ctrl + Shift + P).
- Run "Claude Code: Add MCP Server".
- Configure:
{
"name": "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"
}
}
}
}
Continue.dev (VS Code/JetBrains)
Add to your config.json:
{
"mcpServers": [
{
"name": "nanobanana",
"command": "uvx",
"args": ["nanobanana-mcp-server@latest"],
"env": {
"GEMINI_API_KEY": "your-gemini-api-key-here"
}
}
]
}
Open WebUI
Configure in Open WebUI settings:
{
"mcp_servers": {
"nanobanana": {
"command": ["uvx", "nanobanana-mcp-server@latest"],
"env": {
"GEMINI_API_KEY": "your-gemini-api-key-here"
}
}
}
}
Gemini CLI / Generic MCP Client
export GEMINI_API_KEY="your-gemini-api-key-here"
uvx nanobanana-mcp-server@latest
python -m nanobanana_mcp_server.server
๐ค Model Selection
Nano Banana supports two Gemini models with intelligent automatic selection:
๐ Pro Model - Nano Banana Pro (Gemini 3 Pro Image) โญ NEW!
Google's latest and most advanced image generation model
- Quality: Professional - grade, production - ready.
- Resolution: Up to 4K (3840px) - highest available.
- Speed: ~5 - 8 seconds per image.
- Special Features:
- ๐ Google Search Grounding: Leverages real - world knowledge for accurate, contextual images.
- ๐ง Advanced Reasoning: Configurable thinking levels (LOW/HIGH) for complex compositions.
- ๐ Media Resolution Control: Fine - tune vision processing detail (LOW/MEDIUM/HIGH/AUTO).
- ๐ Superior Text Rendering: Exceptional clarity for text - in - image generation.
- ๐จ Enhanced Context Understanding: Better interpretation of complex, narrative prompts.
- Best for: Production assets, marketing materials, professional photography, high - fidelity outputs, images requiring text, factual accuracy.
- Cost: Higher per image (premium quality).
โก Flash Model (Gemini 2.5 Flash Image)
Fast, reliable model for rapid iteration
- Speed: Very fast (2 - 3 seconds).
- Resolution: Up to 1024px.
- Quality: High quality for everyday use.
- Best for: Rapid prototyping, iterations, high - volume generation, drafts, sketches.
- Cost: Lower per image.
๐ค Automatic Selection (Recommended)
By default, the server uses AUTO mode which intelligently analyzes your prompt and requirements:
Pro Model Selected When:
- Quality keywords detected: "4K", "professional", "production", "high - res", "HD".
- High resolution requested:
resolution="4k" or resolution="high".
- Google Search grounding enabled:
enable_grounding=True.
- High thinking level requested:
thinking_level="HIGH".
- Multi - image conditioning with multiple input images.
Flash Model Selected When:
- Speed keywords detected: "quick", "draft", "sketch", "rapid".
- High - volume batch generation:
n > 2.
- Standard or lower resolution requested.
- No special Pro features required.
Usage Examples
"Generate a professional 4K product photo"
"Quick sketch of a cat"
"Create a diagram with clear text labels"
"Draft mockup for website hero section"
generate_image(
prompt="A scenic landscape",
model_tier="flash"
)
generate_image(
prompt="Professional product photo of vintage camera on wooden desk",
model_tier="pro",
resolution="4k",
thinking_level="HIGH",
enable_grounding=True,
media_resolution="HIGH"
)
generate_image(
prompt="Infographic showing 2024 market statistics with clear labels",
model_tier="pro",
resolution="4k"
)
generate_image(
prompt="Cinematic landscape at sunset",
aspect_ratio="21:9"
)
generate_image(
prompt="Instagram post about coffee",
aspect_ratio="1:1"
)
generate_image(
prompt="YouTube thumbnail design",
aspect_ratio="16:9"
)
generate_image(
prompt="Mobile wallpaper of mountain vista",
aspect_ratio="9:16"
)
๐ Aspect Ratio Control โญ NEW!
Control the output image dimensions with the aspect_ratio parameter:
Supported Aspect Ratios:
1:1 - Square (Instagram, profile pictures).
4:3 - Classic photo format.
3:4 - Portrait orientation.
16:9 - Widescreen (YouTube thumbnails, presentations).
9:16 - Mobile portrait (phone wallpapers, stories).
21:9 - Ultra - wide cinematic.
2:3, 3:2, 4:5, 5:4 - Various photo formats.
generate_image(
prompt="Product showcase for e-commerce",
aspect_ratio="3:4",
model_tier="pro"
)
generate_image(
prompt="Social media banner for Facebook",
aspect_ratio="16:9"
)
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".
โ๏ธ Environment Variables
Configuration options:
GEMINI_API_KEY=your-gemini-api-key-here
NANOBANANA_AUTH_METHOD=vertex_ai
GCP_PROJECT_ID=your-project-id
GCP_REGION=us-central1
NANOBANANA_MODEL=auto
IMAGE_OUTPUT_DIR=/path/to/image/directory
LOG_LEVEL=INFO
LOG_FORMAT=standard
๐ Troubleshooting
Common Issues
"GEMINI_API_KEY not set"
- Add your API key to the MCP server configuration in your client.
- Get a free API key at Google AI Studio.
"Server failed to start"
- 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:
git clone https://github.com/zhongweili/nanobanana-mcp-server.git
cd nanobanana-mcp-server
uv sync
export GEMINI_API_KEY=your-api-key-here
uv run python -m nanobanana_mcp_server.server
๐ License
MIT License - see LICENSE for details.
๐ Support