NanoBanana MCP Server

An MCP (Model Context Protocol) server that connects to the Google Gemini API to generate and edit images using the Nano Banana Pro image generation model.

Features

• Text-to-Image Generation — Describe an image and get it generated via the Gemini API.

• Image Editing — Provide one or more existing images and a text instruction to edit or transform them.

• Multi-Image Input — Send multiple images for blending, style transfer, collages, and more.

• Batch Mode — Submit many prompts at once at 50% reduced cost. Jobs run async and results are polled/downloaded automatically.

• Aspect Ratio Control — Force output to a specific aspect ratio (1:1, 16:9, 9:16, etc.).

• File Output — Save generated images directly to disk with key-based filenames.

• Job Tracking — Batch jobs are persisted to data/batch_jobs.json with full state, input JSONL, and output references.

Related MCP server: Gemini Flash Image MCP Server

Prerequisites

• Node.js >= 18

• A Google Gemini API key — get one at Google AI Studio

Installation

git clone https://github.com/slackermafia/NanoBanana-MCP-Server.git
cd NanoBanana-MCP-Server
npm install

Configuration

Set your Gemini API key as an environment variable:

export GEMINI_API_KEY="your-api-key-here"

Claude Desktop / Cowork

Add this to your MCP server configuration:

{
  "mcpServers": {
    "nanobanana": {
      "command": "node",
      "args": ["/absolute/path/to/NanoBanana-MCP-Server/src/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Tools

gemini_generate_image

Generate an image from a text prompt (synchronous, single image).

gemini_edit_image

Edit one or more images using a text instruction (synchronous).

* You must provide at least one image via image_paths or image_base64_list.

gemini_batch_submit

Submit a batch of image generation requests at 50% reduced cost. Jobs run asynchronously (typically completes within 24 hours).

Each request object in the requests array:

{
  "key": "pink-flamingo",
  "prompt": "A neon pink flamingo sign on a dark wall",
  "aspect_ratio": "1:1",
  "image_paths": "/optional/reference/image.jpg"
}

The key is used as the output filename — so "pink-flamingo" produces pink-flamingo.jpg. This is how you match input prompts to output images.

A JSONL input file is saved to data/ for debugging, and the job ID is tracked in data/batch_jobs.json.

gemini_batch_status

Check the status of pending batch jobs.

Returns the current state of each job: JOB_STATE_PENDING, JOB_STATE_RUNNING, JOB_STATE_SUCCEEDED, JOB_STATE_FAILED, or JOB_STATE_CANCELLED.

gemini_batch_results

Download and save images from completed batch jobs.

Downloads the output JSONL from Gemini, decodes each image, and saves it using the key as the filename. Also saves the raw output JSONL to data/ for debugging.

Batch Workflow

1. Submit batch     →  gemini_batch_submit (creates JSONL, uploads, starts job)
2. Wait             →  Job runs async on Google's side (up to 24h, usually faster)
3. Check status     →  gemini_batch_status (poll for completion)
4. Download results →  gemini_batch_results (saves images to output_dir as {key}.jpg)

A Cowork scheduled task (nanobanana-batch-poll) can be set up to automatically poll every hour and download results when jobs complete.

File Structure

NanoBanana-MCP-Server/
├── src/
│   ├── index.js          # MCP server with all 5 tools
│   └── batch.js          # Batch API helpers, JSONL builder, job tracking
├── data/
│   ├── batch_jobs.json   # Tracked batch jobs (state, IDs, paths)
│   ├── batch_input_*.jsonl   # Input JSONL files (for debugging)
│   └── batch_output_*.jsonl  # Output JSONL files (for debugging)
├── package.json
└── README.md

Supported Aspect Ratios

1:1, 3:2, 2:3, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9

License

MIT