io.github.zhongweili/nanobanana-mcp-server

Install

Config snippet generator goes here (5 client tabs)

README

# Nano Banana MCP Server 🍌

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! 🍌🚀

**Nano Banana 2** (`gemini-3.1-flash-image-preview`) is now the **default model** — delivering Pro-level quality at Flash speed:

- 🍌 **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

<a href="https://glama.ai/mcp/servers/@zhongweili/nanobanana-mcp-server">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@zhongweili/nanobanana-mcp-server/badge" alt="nanobanana-mcp-server MCP server" />
</a>

## ✨ 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

## 🚀 Quick Start

### Prerequisites

1. **Google Gemini API Key** - [Get one free here](https://makersuite.google.com/app/apikey)
2. **Python 3.11+** (for development only)

### Installation

Option 1: From MCP Registry (Recommended)
This 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.

mcp-name: io.github.zhongweili/nanobanana-mcp-server

Option 2: Using `uvx`

```bash
uvx nanobanana-mcp-server@latest
```

Option 3: Using `pip`

```bash
pip install nanobanana-mcp-server
```

## 🔧 Configuration

### Authentication Methods

Nano Banana supports two authentication methods via `NANOBANANA_AUTH_METHOD`:

1. **API Key** (`api_key`): Uses `GEMINI_API_KEY`. Best for local development and simple deployments.
2. **Vertex AI ADC** (`vertex_ai`): Uses Google Cloud Application Default Credentials. Best for production on Google Cloud (Cloud Run, GKE, GCE).
3. **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`:

```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:

```json
{
  "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):

```json
{
  "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:

1. Install the Claude Code extension
2. Open Command Palette