# nanobanana-mcp-server [Health: Active]

**Category:** 🎥 Multimedia Process  
**Repository:** https://github.com/zhongweili/nanobanana-mcp-server  
**GitHub Stars:** 411  
**Views:** 8  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/nanobanana-mcp-server

## Description
AI image generation with Gemini 3 Pro (4K) and 2.5 Flash. Smart model selection.

## Tools
Capabilities this server exposes over MCP:

- **generate_image** — Generate new images or edit existing images using natural language instructions.

Supports multiple input modes:
1. Pure generation: Just provide a prompt to create new images
2. Multi-image conditioning: Provide up to 3 input images using input_image_path_1/2/3 parameters
3. File ID editing: Edit previously uploaded images using Files API ID
4. File path editing: Edit local images by providing single input image path

Automatically detects mode based on parameters or can be explicitly controlled.
Input images are read from the local filesystem to avoid massive token usage.
Returns both MCP image content blocks and structured JSON with metadata.
- **upload_file** — Upload a local file through the Gemini Files API and return its URI & metadata.
Useful when the image is larger than 20MB or reused across prompts.
- **show_output_stats** — Show statistics about the output directory and recently generated images.
- **maintenance** — Perform maintenance operations following workflows.md patterns.

Available operations:
- cleanup_expired: Remove expired Files API entries from database
- cleanup_local: Clean old local files based on age/LRU
- check_quota: Check Files API storage usage vs. ~20GB budget
- database_hygiene: Clean up database inconsistencies
- full_cleanup: Run all cleanup operations in sequence

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "nanobanana-mcp-server": {
    "command": "uvx",
    "args": ["nanobanana-mcp-server@latest"],
    "env": {
      "GEMINI_API_KEY": "",
      "NANOBANANA_AUTH_METHOD": "",
      "GCP_PROJECT_ID": "",
      "GCP_REGION": ""
    }
  }
}
```

**Requires environment variables:** `GEMINI_API_KEY`, `NANOBANANA_AUTH_METHOD`, `GCP_PROJECT_ID`, `GCP_REGION` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What nanobanana-mcp-server MCP server does

nanobanana-mcp-server MCP server gives an MCP-compatible client access to Google's Gemini image models. It supports image generation and editing, with Gemini 3.1 Flash Image used by default. Gemini 3 Pro Image is available for compositions that need deeper reasoning, and Gemini 2.5 Flash Image remains available for fast, lower-resolution iteration.

The server also includes prompt templates for photography, design, and editing workflows. MCP resources allow clients to browse those templates and inspect file metadata. File operations use the Gemini Files API, so the server can upload and manage files used by image workflows.

Aspect ratios can be selected for generated output. Supported examples include 1:1, 16:9, 9:16, and 21:9, with additional ratios described by the project.

## How it works

The server runs as a stdio MCP process and sends image-generation requests to Gemini. Its automatic selection mode routes requests to Nano Banana 2 by default, while prompts that clearly require Pro-level reasoning can be directed to the Pro model. Clients can also request a model tier explicitly:

- `nb2` for Gemini 3.1 Flash Image
- `pro` for Gemini 3 Pro Image
- `flash` for Gemini 2.5 Flash Image
- `auto` for automatic routing

Nano Banana 2 supports output up to 3840 pixels, Google Search grounding, subject consistency for scenes with multiple subjects, and text rendering. The Pro model supports configurable LOW or HIGH thinking levels and media-resolution control. The legacy Flash model is intended for rapid drafts up to 1024 pixels.

## Setup and configuration

nanobanana-mcp-server MCP server can be installed from the MCP Registry, launched with `uvx nanobanana-mcp-server@latest`, or installed with pip. Python 3.11 or newer is listed for development.

For API-key authentication, set `GEMINI_API_KEY`. Google Cloud deployments can use Vertex AI Application Default Credentials instead by setting `NANOBANANA_AUTH_METHOD=vertex_ai`, `GCP_PROJECT_ID`, and `GCP_REGION`. The project documentation lists `auto` as another authentication mode; it uses the API key when available and otherwise attempts Vertex AI. Vertex AI users must enable the Vertex AI API and grant the service account the `roles/aiplatform.user` role.

The documented client configurations cover Claude Desktop, Claude Code in VS Code, Cursor, OpenAI Codex, Continue, Open WebUI, and Gemini CLI. The server can also be started directly with `python -m nanobanana_mcp_server.server` after a pip installation.

## Tools and capabilities

The README identifies these tools for direct client use:

- `generate_image` creates images with a selected or automatically chosen Gemini model.
- `edit_image` edits an existing image through the image workflow.
- `upload_file` uploads files using the Gemini Files API.

Additional capabilities include aspect-ratio selection, reusable prompt templates, file management, resource discovery for templates and file metadata, validation, logging, error handling, and caching.

## Limitations and notes

Model capabilities differ by tier. The documented Vertex AI region is `global` for Nano Banana 2 and Gemini 3 Pro Image; `us-central1` is specified only for the legacy 2.5 Flash Image model.

Using this server requires either a Google Gemini API key or a working Vertex AI ADC setup. Google Search grounding and other model-specific behavior depend on the selected Gemini model.

_Full upstream README: https://allmcps.com/mcp/nanobanana-mcp-server/readme_

