{
  "markdown": "# Nano Banana MCP Server 🍌\n\nA production-ready **Model Context Protocol (MCP)** server that provides AI-powered image generation capabilities through Google's **Gemini** models with intelligent model selection.\n\n## ⭐ NEW: Nano Banana 2 — Gemini 3.1 Flash Image! 🍌🚀\n\n**Nano Banana 2** (`gemini-3.1-flash-image-preview`) is now the **default model** — delivering Pro-level quality at Flash speed:\n\n- 🍌 **Flash Speed + 4K Quality**: Up to 3840px at Gemini 2.5 Flash latency\n- 🌐 **Google Search Grounding**: Real-world knowledge for factually accurate images\n- 🎯 **Subject Consistency**: Up to 5 characters and 14 objects per scene\n- ✍️ **Precision Text Rendering**: Crystal-clear text placement in images\n- 🏆 **Gemini 3 Pro Image** still available for maximum reasoning depth\n\n<a href=\"https://glama.ai/mcp/servers/@zhongweili/nanobanana-mcp-server\">\n  <img width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/@zhongweili/nanobanana-mcp-server/badge\" alt=\"nanobanana-mcp-server MCP server\" />\n</a>\n\n## ✨ Features\n\n- 🎨 **Multi-Model AI Image Generation**: Three Gemini models with intelligent automatic selection\n- 🍌 **Gemini 3.1 Flash Image (NB2)**: Default model — 4K resolution at Flash speed with grounding\n- 🏆 **Gemini 3 Pro Image**: Maximum reasoning depth for the most complex compositions\n- ⚡ **Gemini 2.5 Flash Image**: Legacy Flash model for high-volume rapid prototyping\n- 🤖 **Smart Model Selection**: Automatically routes to NB2 or Pro based on your prompt\n- 📐 **Aspect Ratio Control** ⭐ NEW: Specify output dimensions (1:1, 16:9, 9:16, 21:9, and more)\n- 📋 **Smart Templates**: Pre-built prompt templates for photography, design, and editing\n- 📁 **File Management**: Upload and manage files via Gemini Files API\n- 🔍 **Resource Discovery**: Browse templates and file metadata through MCP resources\n- 🛡️ **Production Ready**: Comprehensive error handling, logging, and validation\n- ⚡ **High Performance**: Optimized architecture with intelligent caching\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n1. **Google Gemini API Key** - [Get one free here](https://makersuite.google.com/app/apikey)\n2. **Python 3.11+** (for development only)\n\n### Installation\n\nOption 1: From MCP Registry (Recommended)\nThis server is available in the [Model Context Protocol Registry](https://registry.modelcontextprotocol.io/?q=nanobanana). Search for \"nanobanana\" or use the MCP name below with your MCP client.\n\nmcp-name: io.github.zhongweili/nanobanana-mcp-server\n\nOption 2: Using `uvx`\n\n```bash\nuvx nanobanana-mcp-server@latest\n```\n\nOption 3: Using `pip`\n\n```bash\npip install nanobanana-mcp-server\n```\n\n## 🔧 Configuration\n\n### Authentication Methods\n\nNano Banana supports two authentication methods via `NANOBANANA_AUTH_METHOD`:\n\n1. **API Key** (`api_key`): Uses `GEMINI_API_KEY`. Best for local development and simple deployments.\n2. **Vertex AI ADC** (`vertex_ai`): Uses Google Cloud Application Default Credentials. Best for production on Google Cloud (Cloud Run, GKE, GCE).\n3. **Automatic** (`auto`): Defaults to API Key if present, otherwise tries Vertex AI.\n\n#### 1. API Key Authentication (Default)\n\nSet `GEMINI_API_KEY` environment variable.\n\n#### 2. Vertex AI Authentication (Google Cloud)\n\nRequired environment variables:\n\n- `NANOBANANA_AUTH_METHOD=vertex_ai` (or `auto`)\n- `GCP_PROJECT_ID=your-project-id`\n- `GCP_REGION=global` (default; required for Gemini 3 Pro Image and NB2. Use `us-central1` only for the legacy 2.5 Flash Image model.)\n\n**Prerequisites**:\n\n- Enable Vertex AI API: `gcloud services enable aiplatform.googleapis.com`\n- Grant IAM Role: `roles/aiplatform.user` to the service account.\n\n### Claude Desktop\n\n#### Option 1: Using Published Server (Recommended)\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"nanobanana\": {\n      \"command\": \"uvx\",\n      \"args\": [\"nanobanana-mcp-server@latest\"],\n      \"env\": {\n        \"GEMINI_API_KEY\": \"your-gemini-api-key-here\"\n      }\n    }\n  }\n}\n```\n\n#### Option 2: Using Local Source (Development)\n\nIf you are running from source code, point to your local installation:\n\n```json\n{\n  \"mcpServers\": {\n    \"nanobanana-local\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"python\", \"-m\", \"nanobanana_mcp_server.server\"],\n      \"cwd\": \"/absolute/path/to/nanobanana-mcp-server\",\n      \"env\": {\n        \"GEMINI_API_KEY\": \"your-gemini-api-key-here\"\n      }\n    }\n  }\n}\n```\n\n#### Option 3: Using Vertex AI (ADC)\n\nTo authenticate with Google Cloud Application Default Credentials (instead of an API Key):\n\n```json\n{\n  \"mcpServers\": {\n    \"nanobanana-adc\": {\n      \"command\": \"uvx\",\n      \"args\": [\"nanobanana-mcp-server@latest\"],\n      \"env\": {\n        \"NANOBANANA_AUTH_METHOD\": \"vertex_ai\",\n        \"GCP_PROJECT_ID\": \"your-project-id\",\n        \"GCP_REGION\": \"global\"\n      }\n    }\n  }\n}\n```\n\n**Configuration file locations:**\n\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n### Claude Code (VS Code Extension)\n\nInstall and configure in VS Code:\n\n1. Install the Claude Code extension\n2. Open Command Palette (`Cmd/Ctrl + Shift + P`)\n3. Run \"Claude Code: Add MCP Server\"\n4. Configure:\n   ```json\n   {\n     \"name\": \"nanobanana\",\n     \"command\": \"uvx\",\n     \"args\": [\"nanobanana-mcp-server@latest\"],\n     \"env\": {\n       \"GEMINI_API_KEY\": \"your-gemini-api-key-here\"\n     }\n   }\n   ```\n\n### Cursor\n\nAdd to Cursor's MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"nanobanana\": {\n      \"command\": \"uvx\",\n      \"args\": [\"nanobanana-mcp-server@latest\"],\n      \"env\": {\n        \"GEMINI_API_KEY\": \"your-gemini-api-key-here\"\n      }\n    }\n  }\n}\n```\n\n### OpenAI Codex\n\nAdd to `~/.codex/config.toml` (global) or `.codex/config.toml` (project-scoped):\n\n```toml\n[mcp_servers.nanobanana]\ncommand = \"uvx\"\nargs = [\"nanobanana-mcp-server@latest\"]\n\n[mcp_servers.nanobanana.env]\nGEMINI_API_KEY = \"your-gemini-api-key-here\"\n```\n\nOr add via the CLI:\n\n```bash\ncodex mcp add\n```\n\nCodex 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.\n\n> **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.\n\n### Continue.dev (VS Code/JetBrains)\n\nAdd to your `config.json`:\n\n```json\n{\n  \"mcpServers\": [\n    {\n      \"name\": \"nanobanana\",\n      \"command\": \"uvx\",\n      \"args\": [\"nanobanana-mcp-server@latest\"],\n      \"env\": {\n        \"GEMINI_API_KEY\": \"your-gemini-api-key-here\"\n      }\n    }\n  ]\n}\n```\n\n### Open WebUI\n\nConfigure in Open WebUI settings:\n\n```json\n{\n  \"mcp_servers\": {\n    \"nanobanana\": {\n      \"command\": [\"uvx\", \"nanobanana-mcp-server@latest\"],\n      \"env\": {\n        \"GEMINI_API_KEY\": \"your-gemini-api-key-here\"\n      }\n    }\n  }\n}\n```\n\n### Gemini CLI / Generic MCP Client\n\n```bash\n# Set environment variable\nexport GEMINI_API_KEY=\"your-gemini-api-key-here\"\n\n# Run server in stdio mode\nuvx nanobanana-mcp-server@latest\n\n# Or with pip installation\npython -m nanobanana_mcp_server.server\n```\n\n## 🤖 Model Selection\n\nNano Banana supports three Gemini models with intelligent automatic selection:\n\n### 🍌 NB2 — Nano Banana 2 (Gemini 3.1 Flash Image) ⭐ DEFAULT\n\n**Flash speed with Pro-level quality — the best of both worlds**\n\n- **Quality**: Production-ready 4K output\n- **Resolution**: Up to 4K (3840px)\n- **Speed**: ~2-4 seconds per image (Flash-class latency)\n- **Special Features**:\n  - 🌐 **Google Search Grounding**: Real-world knowledge for factually accurate images\n  - 🎯 **Subject Consistency**: Up to 5 characters and 14 objects per scene\n  - ✍️ **Precision Text Rendering**: Clear, well-placed text in images\n- **Best for**: Almost everything — production assets, marketing, photography, text overlays\n- **model_tier**: `\"nb2\"` (or `\"auto\"` — NB2 is the auto default)\n\n### 🏆 Pro Model — Nano Banana Pro (Gemini 3 Pro Image)\n\n**Maximum reasoning depth for the most demanding compositions**\n\n- **Quality**: Highest available\n- **Resolution**: Up to 4K (3840px)\n- **Speed**: ~5-8 seconds per image\n- **Special Features**:\n  - 🧠 **Advanced Reasoning**: Configurable thinking levels (LOW/HIGH)\n  - 🌐 **Google Search Grounding**: Real-world knowledge integration\n  - 📐 **Media Resolution Control**: Fine-tune vision processing detail\n- **Best for**: Complex narrative scenes, intricate compositions, maximum reasoning required\n- **model_tier**: `\"pro\"`\n\n### ⚡ Flash Model (Gemini 2.5 Flash Image)\n\n**Legacy model for high-volume rapid iteration**\n\n- **Speed**: Very fast (2-3 seconds)\n- **Resolution**: Up to 1024px\n- **Best for**: High-volume generation, quick drafts where 4K is not needed\n- **model_tier**: `\"flash\"`\n\n### 🤖 Automatic Selection (Recommended)\n\nBy default, the server uses **AUTO** mode which routes to **NB2** unless Pro's deeper reasoning is clearly needed:\n\n**Pro Model Selected When**:\n\n- Strong quality keywords: \"4K\", \"professional\", \"production\", \"high-res\", \"HD\"\n- High thinking level requested: `thinking_level=\"HIGH\"`\n- Multi-image conditioning with multiple input images\n\n**NB2 Model Selected When** (default):\n\n- Standard requests, everyday image generation\n- Speed keywords: \"quick\", \"draft\", \"sketch\", \"rapid\"\n- High-volume batch generation (`n > 2`)\n\n### Usage Examples\n\n```python\n# Automatic selection (recommended) — routes to NB2 by default\n\"A cat sitting on a windowsill\"             # → NB2 (default)\n\"Quick sketch of a cat\"                     # → NB2 (speed keyword, NB2 is fast enough)\n\"Professional 4K product photo\"             # → Pro (strong quality keywords)\n\n# Explicit NB2 selection\ngenerate_image(\n    prompt=\"Product photo on white background\",\n    model_tier=\"nb2\",              # Nano Banana 2 (Flash speed + 4K)\n    resolution=\"4k\",\n    enable_grounding=True\n)\n\n# Leverage Nano Banana Pro for complex reasoning\ngenerate_image(\n    prompt=\"Cinematic scene: three characters in a tense standoff at dusk\",\n    model_tier=\"pro\",              # Pro for deep reasoning\n    resolution=\"4k\",\n    thinking_level=\"HIGH\",         # Enhanced reasoning\n    enable_grounding=True\n)\n\n# Legacy Flash for high-volume drafts\ngenerate_image(\n    prompt=\"Simple icon\",\n    model_tier=\"flash\"             # Fast 1024px generation\n)\n\n# Control aspect ratio for different formats ⭐ NEW!\ngenerate_image(\n    prompt=\"Cinematic landscape at sunset\",\n    aspect_ratio=\"21:9\"            # Ultra-wide cinematic format\n)\n\ngenerate_image(\n    prompt=\"Instagram post about coffee\",\n    aspect_ratio=\"1:1\"             # Square format for social media\n)\n\ngenerate_image(\n    prompt=\"YouTube thumbnail design\",\n    aspect_ratio=\"16:9\"            # Standard video format\n)\n\ngenerate_image(\n    prompt=\"Mobile wallpaper of mountain vista\",\n    aspect_ratio=\"9:16\"            # Portrait format for phones\n)\n```\n\n### 📐 Aspect Ratio Control\n\nControl the output image dimensions with the `aspect_ratio` parameter:\n\n**Supported Aspect Ratios**:\n\n- `1:1` - Square (Instagram, profile pictures)\n- `4:3` - Classic photo format\n- `3:4` - Portrait orientation\n- `16:9` - Widescreen (YouTube thumbnails, presentations)\n- `9:16` - Mobile portrait (phone wallpapers, stories)\n- `21:9` - Ultra-wide cinematic\n- `2:3`, `3:2`, `4:5`, `5:4` - Various photo formats\n\n```python\n# Examples for different use cases\ngenerate_image(\n    prompt=\"Product showcase for e-commerce\",\n    aspect_ratio=\"3:4\",    # Portrait format, good for product pages\n    model_tier=\"pro\"\n)\n\ngenerate_image(\n    prompt=\"Social media banner for Facebook\",\n    aspect_ratio=\"16:9\"    # Landscape banner format\n)\n```\n\n**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\"`.\n\n### 📁 Output Path Control ⭐ NEW!\n\nControl where generated images are saved with the `output_path` parameter:\n\n**Three modes of operation:**\n\n1. **Specific file path** - Save to an exact file location:\n\n```python\ngenerate_image(\n    prompt=\"A beautiful sunset\",\n    output_path=\"/path/to/sunset.png\"  # Exact file location\n)\n```\n\n2. **Directory path** - Use auto-generated filename in a specific directory:\n\n```python\ngenerate_image(\n    prompt=\"Product photo\",\n    output_path=\"/path/to/products/\"  # Trailing slash indicates directory\n)\n```\n\n3. **Default location** - Uses IMAGE_OUTPUT_DIR or ~/nanobanana-images:\n\n```python\ngenerate_image(\n    prompt=\"Random image\"\n    # output_path defaults to None\n)\n```\n\n**Multiple images (n > 1):**\nWhen generating multiple images with a file path, images are automatically numbered:\n\n- First image: `/path/to/image.png`\n- Second image: `/path/to/image_2.png`\n- Third image: `/path/to/image_3.png`\n\n**Precedence Rules:**\n\n1. `output_path` parameter (if provided) - highest priority\n2. `IMAGE_OUTPUT_DIR` environment variable\n3. `~/nanobanana-images` (default fallback)\n\n```python\n# Save to specific location with Pro model\ngenerate_image(\n    prompt=\"Professional headshot\",\n    model_tier=\"pro\",\n    output_path=\"/Users/me/photos/headshot.png\"\n)\n\n# Save multiple images to a directory\ngenerate_image(\n    prompt=\"Product variations\",\n    n=4,\n    output_path=\"/path/to/products/\"  # Each gets unique filename\n)\n```\n\n## ⚙️ Environment Variables\n\nConfiguration options:\n\n```bash\n# Authentication (Required)\n# Method 1: API Key\nGEMINI_API_KEY=your-gemini-api-key-here\n\n# Method 2: Vertex AI (Google Cloud)\nNANOBANANA_AUTH_METHOD=vertex_ai\nGCP_PROJECT_ID=your-project-id\nGCP_REGION=global  # Required for gemini-3-pro-image-preview and NB2; use \"us-central1\" only for legacy 2.5 Flash Image\n\n# Model Selection (optional)\nNANOBANANA_MODEL=auto  # Options: flash, nb2, pro, auto (default: auto → nb2)\n\n# Optional\nIMAGE_OUTPUT_DIR=/path/to/image/directory  # Default: ~/nanobanana-images\nGEMINI_BASE_URL=https://custom-api.example.com  # Custom API endpoint (for proxies/gateways)\nLOG_LEVEL=INFO                             # DEBUG, INFO, WARNING, ERROR\nLOG_FORMAT=standard                        # standard, json, detailed\n```\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n**\"GEMINI_API_KEY not set\"**\n\n- Add your API key to the MCP server configuration in your client\n- Get a free API key at [Google AI Studio](https://makersuite.google.com/app/apikey)\n\n**\"Server failed to start\"**\n\n- Ensure you're using the latest version: `uvx nanobanana-mcp-server@latest`\n- Check that your client supports MCP (Claude Desktop 0.10.0+)\n\n**\"Permission denied\" errors**\n\n- The server creates images in `~/nanobanana-images` by default\n- Ensure write permissions to your home directory\n\n### Development Setup\n\nFor local development:\n\n```bash\n# Clone repository\ngit clone https://github.com/zhongweili/nanobanana-mcp-server.git\ncd nanobanana-mcp-server\n\n# Install with uv\nuv sync\n\n# Set environment\nexport GEMINI_API_KEY=your-api-key-here\n\n# Run locally\nuv run python -m nanobanana_mcp_server.server\n```\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## 🆘 Support\n\n- **Issues**: [GitHub Issues](https://github.com/zhongweili/nanobanana-mcp-server/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/zhongweili/nanobanana-mcp-server/discussions)\n",
  "bytes": 15178,
  "sha": "dd13bb54c9bd5ca70df12a815fd2fa849d98df0047fd595c11e9aff74a740f26",
  "repo_slug": "zhongweili/nanobanana-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_zhongweili_nanobanana_mcp_serv_28cdc89b/readme"
}