NanoBanana MCP Server

Model Context Protocol server for Google Gemini NanoBanana image AI generation and editing. Supports the full Nano Banana family: 2.5 Flash Image, 3 Pro Image (Nano Banana Pro), 3.1 Flash Image (Nano Banana 2), and 3.1 Flash Lite Image (Nano Banana 2 Lite).

🚀 Installation

Global Installation (Recommended)

Install globally via npm:

npm install -g nanobanana-mcp-server

After installation, the server will be available as nanobanana-mcp command.

Local Development Installation

git clone <repository-url>
cd Gemini2.5FlashImageMCPServer
npm install
npm run build

⚙️ Configuration

Environment Variables

Create a .env file or set environment variables:

GEMINI_API_KEY=your_gemini_api_key_here
NANOBANANA_OUTPUT_DIR=~/Downloads/nanobanana-images
DEBUG=false
MCP_SERVER_NAME=nanobanana-mcp-server

Claude Desktop Integration

Global Installation Setup

Add to your Claude Desktop configuration (%APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "nanobanana": {
      "command": "nanobanana-mcp",
      "env": {
        "GEMINI_API_KEY": "your_gemini_api_key_here",
        "NANOBANANA_OUTPUT_DIR": "C:\\Users\\YourUsername\\Downloads\\nanobanana-images",
        "DEBUG": "false"
      }
    }
  }
}

Local Installation Setup

{
  "mcpServers": {
    "nanobanana": {
      "command": "node",
      "args": ["path/to/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your_gemini_api_key_here",
        "NANOBANANA_OUTPUT_DIR": "path/to/output/directory",
        "DEBUG": "false"
      }
    }
  }
}

🎨 Available Tools

generate_image

Generate images from text prompts with optional style, aspect ratio, and reference images for style/content guidance.

Parameters:

• prompt (required): Text description of the image
• style (optional): Style specification (e.g., "photorealistic", "artistic", "cartoon")
• aspectRatio (optional): Aspect ratio (e.g., "16:9", "4:3", "1:1", "9:16")
• referenceImagePaths (optional): Array of reference image paths for style/content guidance
  • gemini-2.5-flash-image: max 3 images
  • gemini-3-pro-image / gemini-3.1-flash-image / gemini-3.1-flash-lite-image: max 14 images
  • Note: gemini-3.1-flash-lite-image accepts object references but does not support character consistency / style references
• model (optional): gemini-2.5-flash-image, gemini-3-pro-image, gemini-3.1-flash-image, or gemini-3.1-flash-lite-image (default: gemini-3-pro-image)
• resolution (optional): 512, 1K, 2K, or 4K (Gemini 3 models; gemini-3.1-flash-lite-image is 1K only)
• output_path (optional): Custom output path

Example (text only):

{
  "prompt": "A serene mountain lake at sunset with reflections",
  "aspectRatio": "16:9",
  "style": "photorealistic"
}

Example (with reference images):

{
  "prompt": "Generate a new scene with this character looking at snowy night sky",
  "referenceImagePaths": ["./character_sheet.png"],
  "aspectRatio": "3:4",
  "model": "gemini-3-pro-image",
  "resolution": "1K"
}

edit_image

Edit existing images using natural language instructions.

Parameters:

• imagePath (required): Path to input image
• instruction (required): Editing instruction
• outputPath (optional): Custom output path

multi_image_fusion

Blend multiple images into a single image.

Parameters:

• imagePaths (required): Array of image paths
  • gemini-2.5-flash-image: max 3 images
  • gemini-3-pro-image / gemini-3.1-flash-image / gemini-3.1-flash-lite-image: max 14 images
• instruction (required): Fusion instructions
• model (optional): gemini-2.5-flash-image, gemini-3-pro-image, gemini-3.1-flash-image, or gemini-3.1-flash-lite-image
• resolution (optional): 512, 1K, 2K, or 4K (Gemini 3 models; gemini-3.1-flash-lite-image is 1K only)
• output_path (optional): Custom output path

character_consistency

Create new images with consistent character from reference.

Parameters:

• characterImagePath (required): Reference character image
• scenePrompt (required): New scene description
• outputPath (optional): Custom output path

list_generated_images

List all generated images with metadata.

Parameters:

• limit (optional): Maximum number of images (default: 50)

📏 Supported Aspect Ratios

| Ratio | Description | Resolution | |-------|-------------|------------| | 16:9 | Widescreen | 1920×1080 | | 9:16 | Portrait (mobile) | 1080×1920 | | 4:3 | Standard | 1600×1200 | | 3:4 | Portrait | 1200×1600 | | 1:1 | Square | 1024×1024 | | 3:2 | Photo standard | 1536×1024 | | 2:3 | Portrait photo | 1024×1536 | | 21:9 | Ultrawide | 2560×1097 |

🔧 Usage

MCP Server (for Claude Desktop)

# Start the MCP server
nanobanana-mcp

# Or with environment variables
GEMINI_API_KEY=your_key nanobanana-mcp

Batch CLI (for command line)

# Basic batch processing
nanobanana-batch batch.json

# Specify output directory
nanobanana-batch batch.json --output-dir ./my-images

# JSON output for scripting
nanobanana-batch batch.json --format json > result.json

# Custom timeout (20 minutes)
nanobanana-batch batch.json --timeout 1200000

# Show help
nanobanana-batch --help

Programmatic Usage

# Local development (MCP server)
npm run dev

# Local development (Batch CLI)
npm run dev:batch batch.json

# Production
npm start        # MCP server
npm run batch    # Batch CLI

📦 Batch Processing

The nanobanana-batch command processes multiple image jobs from a JSON configuration file.

Batch Config Format

{
  "jobs": [
    {
      "type": "generate",
      "prompt": "A beautiful sunset over mountains",
      "output_filename": "sunset.png",
      "aspectRatio": "16:9",
      "style": "photorealistic"
    },
    {
      "type": "generate",
      "prompt": "This character gazing at snowy night sky",
      "referenceImagePaths": ["./character_sheet.png"],
      "output_filename": "character_snow.png",
      "aspectRatio": "3:4",
      "model": "gemini-3-pro-image-preview",
      "resolution": "1K"
    },
    {
      "type": "edit",
      "imagePath": "./input.png",
      "instruction": "Make it more vibrant",
      "output_filename": "edited.png"
    },
    {
      "type": "fusion",
      "imagePaths": ["./a.png", "./b.png"],
      "instruction": "Blend the styles together"
    },
    {
      "type": "character",
      "characterImagePath": "./character.png",
      "scenePrompt": "In a magical forest"
    }
  ],
  "output_dir": "./output",
  "max_concurrent": 2,
  "timeout": 600000
}

Supported Job Types

| Type | Required Fields | Optional Fields | Description | |------|-----------------|-----------------|-------------| | generate | prompt | referenceImagePaths[], style | Text-to-image generation with optional reference images | | edit | imagePath, instruction | | Edit existing image | | fusion | imagePaths[], instruction | | Blend multiple images | | character | characterImagePath, scenePrompt | | Character consistency |

Common Job Options

All job types support these optional fields:

• output_filename: Custom output filename
• model: gemini-2.5-flash-image, gemini-3-pro-image, gemini-3.1-flash-image, or gemini-3.1-flash-lite-image
• resolution: 512, 1K, 2K, or 4K (Gemini 3 models; gemini-3.1-flash-lite-image is 1K only)
• aspectRatio: 1:1, 16:9, 9:16, etc.

Legacy *-preview model IDs (gemini-3-pro-image-preview, gemini-3.1-flash-image-preview, gemini-3.1-flash-lite-image-preview) are still accepted for backward compatibility and are auto-mapped to their GA IDs (the preview endpoints were shut down 2026-06-25).

Batch CLI Options

| Option | Description | |--------|-------------| | --output-dir <path> | Output directory (overrides config and env) | | --format <text\|json> | Output format (default: text) | | --timeout <ms> | Timeout in milliseconds (default: 600000) | | --help, -h | Show help | | --version, -v | Show version |

🛠 Development

Build

npm run build

Clean

npm run clean

📋 Requirements

• Node.js 18+
• Google Gemini API key
• Claude Desktop (for MCP integration)

🤖 Model Comparison

| Feature | gemini-2.5-flash-image | gemini-3.1-flash-lite-image | gemini-3.1-flash-image | gemini-3-pro-image | |---------|------------------------|-----------------------------|------------------------|--------------------| | Nickname | Nano Banana | Nano Banana 2 Lite | Nano Banana 2 | Nano Banana Pro | | Speed | Fast (~5-10s) | Fastest (sub-2s) | Fast | Slower (~20-30s) | | Resolution | 1K (fixed) | 1K (fixed) | 512 / 1K / 2K / 4K | 1K / 2K / 4K | | Max Reference Images | 3 | 14 (objects only) | 14 | 14 | | Character Consistency | Limited | Not supported | Up to 4 characters | Up to 5 characters | | Aspect Ratio | Via prompt | Via API parameter | Via API parameter | Via API parameter | | Google Search Grounding | No | No | Yes | Yes | | Best For | Quick iterations | High-volume, low cost | All-around workhorse | Highest quality output |

💰 Pricing

• Gemini 2.5 Flash Image (Nano Banana): Free tier available (60 requests/min via AI Studio). Legacy — migrating to Nano Banana 2 Lite is recommended.
• Gemini 3.1 Flash Lite Image (Nano Banana 2 Lite): Fastest and cheapest of the family. Requires billing enabled.
• Gemini 3.1 Flash Image (Nano Banana 2): ~$0.0672/image (half of Pro). Requires billing enabled.
• Gemini 3 Pro Image (Nano Banana Pro): Premium tier. Requires billing enabled.

See the official pricing page for the latest rates.

📄 License

MIT License