Gemini Nano Banana MCP

An MCP (Model Context Protocol) server for AI-powered image generation, editing, and video generation using Google Gemini and Veo. Works with Claude Code, Cursor, and any MCP-compatible client.

Features

• Text-to-Image Generation - Generate images from text prompts via Gemini AI
• Image Editing - Edit existing images with natural language instructions
• Reference Images - Use reference images for style and content guidance
• Text-to-Video Generation - Generate videos from text prompts using Veo (veo-3.1, veo-3, veo-2)
• Image-to-Video - Use an image as the first frame for video generation
• First & Last Frame Interpolation - Generate videos between two keyframe images
• Session Memory - Continue editing the last image without re-specifying the path
• Configurable Models - Choose any Gemini model for images, any Veo model for videos
• Media History - Track and browse recently generated images and videos
• Cross-Platform - Works on macOS, Windows, and Linux

Quick Start

1. Get a Gemini API Key

Get your free API key from Google AI Studio.

2. Install

npm install -g @seungmanchoi/nano-banana-mcp

Or install from source:

git clone https://github.com/seungmanchoi/nano-banana-mcp.git
cd nano-banana-mcp
npm install
npm run build

3. Configure Your MCP Client

#### Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "nano-banana": {
      "command": "npx",
      "args": ["-y", "@seungmanchoi/nano-banana-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

#### Cursor

Add to your MCP settings:

{
  "mcpServers": {
    "nano-banana": {
      "command": "npx",
      "args": ["-y", "@seungmanchoi/nano-banana-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

#### From Source

If installed from source, use the absolute path:

{
  "mcpServers": {
    "nano-banana": {
      "command": "node",
      "args": ["/absolute/path/to/nano-banana-mcp/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

You can also skip the env field and configure the API key at runtime using the configure_api_key tool.

Authentication Modes

This server supports two authentication modes. The default is API key mode (above).

Mode A — API key (official, default)

Uses a Gemini API key from Google AI Studio. Supports image generation, image editing, and video (Veo). Note that image generation models are largely a paid feature.

Mode B — Free Google-cookie mode (consumer Gemini, unofficial)

Drives your logged-in gemini.google.com session via its session cookies instead of an API key. Free, and supports image generation + editing only (no video).

⚠️ This mode is unofficial. It talks to an undocumented internal endpoint, not the official API. It may break when Google changes things, cookies expire periodically and must be re-extracted, and use is a Terms-of-Service gray area. Intended for personal use with your own account.

1. Extract your cookies from a browser where you're logged into gemini.google.com:

1. Open https://gemini.google.com and sign in.
2. DevTools (F12) → Application → Cookies → https://gemini.google.com.
3. Copy the value of __Secure-1PSID (required) and __Secure-1PSIDTS (recommended).

2a. Configure via environment variables:

{
  "mcpServers": {
    "nano-banana": {
      "command": "npx",
      "args": ["-y", "@seungmanchoi/nano-banana-mcp"],
      "env": {
        "GEMINI_AUTH_MODE": "gemini-web",
        "GEMINI_SECURE_1PSID": "your-__Secure-1PSID-value",
        "GEMINI_SECURE_1PSIDTS": "your-__Secure-1PSIDTS-value"
      }
    }
  }
}

2b. Or configure at runtime with the configure_google_login tool:

Use configure_google_login with secure1psid "<...>" and secure1psidts "<...>"

This switches the active mode to gemini-web and persists to ~/.nano-banana/config.json. Run configure_api_key again at any time to switch back to API key mode.

Model Configuration

Image Models

The default image model is gemini-2.0-flash-preview-image-generation. You can change it in several ways:

#### Option 1: Environment Variable

Set GEMINI_MODEL in your MCP client config:

{
  "mcpServers": {
    "nano-banana": {
      "command": "npx",
      "args": ["-y", "@seungmanchoi/nano-banana-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here",
        "GEMINI_MODEL": "gemini-2.0-flash-preview-image-generation"
      }
    }
  }
}

#### Option 2: Runtime Tool

Use the configure_model tool to change the default model at runtime. The setting persists across sessions in ~/.nano-banana/config.json.

Set the model to imagen-3.0-generate-002

#### Option 3: Per-Request Override

Pass the model parameter directly to generate_image, edit_image, or continue_editing to override the default for a single request:

Generate an image of a cat using model imagen-3.0-generate-002

Model Priority

1. Per-request `model` parameter (highest priority)
2. `GEMINI_MODEL` environment variable
3. Config file (~/.nano-banana/config.json)
4. Default: gemini-2.0-flash-preview-image-generation

Available Image Models

Note: Free-tier API keys support gemini-2.0-flash-preview-image-generation. Imagen models require billing enabled on your Google Cloud project.

Available Video Models

For the latest list of models, see Google AI documentation.

Tools

Image Tools

Video Tools

Utility Tools

Usage Examples

Image Generation

Generate an image of a sunset over mountains with a lake reflection

Edit the image at ~/nano-banana-images/gen_2025-01-01.png to add a boat on the lake

Continue editing - make the sky more vibrant with orange and pink tones

Video Generation

Generate a video of ocean waves crashing on a rocky shore at sunset

Generate a video of a cat playing with yarn, model veo-3.1-generate-preview, resolution 1080p, duration 8 seconds

#### Image-to-Video (First Frame)

Generate a video starting from the image at ~/nano-banana-images/gen_2025-01-01.png showing the scene coming to life with wind blowing through the trees

#### First + Last Frame Interpolation

Generate a video transitioning from the image at ~/images/start.png to ~/images/end.png with a smooth camera pan

#### Portrait Video

Generate a video of a person walking through a garden, aspect ratio 9:16

History & Status

Show me the last 5 images I generated

Show me recent video history

Check the current status

Switch to imagen-3.0-generate-002 model for higher quality

Video Generation Details

Configuration Options

Generation Modes

1. Text-to-Video: Provide only a prompt
2. Image-to-Video: Provide prompt + imagePath (used as first frame)
3. Frame Interpolation: Provide prompt + imagePath (first frame) + lastFramePath (last frame)

Important Notes

• Video generation takes 1-6 minutes depending on load
• Generated videos are saved as .mp4 files
• Videos are watermarked with SynthID technology
• Pricing: $0.75 per second of generated video
• Videos are retained on Google servers for 2 days after generation

API Key Configuration

The server loads the API key in the following priority order:

1. Environment variable - GEMINI_API_KEY
2. Config file - ~/.nano-banana/config.json
3. Runtime - via the configure_api_key tool

File Storage

Images

Videos

Project Structure

src/
├── index.ts              # Entry point
├── server.ts             # MCP server setup and request routing
├── config/
│   └── settings.ts       # API key and model management
├── services/
│   ├── gemini.ts         # Google Gemini & Veo API client
│   └── storage.ts        # Image/video file I/O and history tracking
├── tools/
│   ├── definitions.ts    # MCP tool schemas
│   └── handlers.ts       # Tool request handlers
└── types/
    └── index.ts          # TypeScript type definitions

Development

npm run dev          # Run with tsx (no build needed)
npm run build        # Compile TypeScript
npm run typecheck    # Type check without emitting
npm run lint         # Run ESLint

Tech Stack

• Runtime: Node.js
• Language: TypeScript (strict mode, ES2022)
• MCP SDK: @modelcontextprotocol/sdk
• AI Models: Google Gemini (images) + Veo (videos)
• Validation: Zod

License

MIT