# nanobanana-mcp-server

An MCP server that hands your coding agent image generation and editing through Gemini models. Useful when you want pictures without leaving the session.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed · ★ 401
- Author: zhongweili
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/zhongweili/nanobanana-mcp-server
- Updated: 2026-10-20
- HTML: https://affpapa.org/en/nevibecode/mcp/nanobanana-mcp-server

## What it does

The server plugs into Claude, Codex, Cursor, GitHub Copilot, Windsurf, Cline and Zed, exposing three tools to the agent: `generate_image`, `edit_image` and `upload_file`. Requests go to Gemini models, and the server picks which one fits your prompt. The default is `gemini-3.1-flash-image-preview` — Nano Banana 2, which renders up to 3840px. `Gemini 3 Pro Image` stays available when a composition needs deeper reasoning, and `Gemini 2.5 Flash Image` remains as the older fast option.

You get aspect ratio control (1:1, 16:9, 9:16, 21:9 and others), ready-made prompt templates for photography, design and editing, plus file handling through the Gemini Files API. Templates and file metadata show up to the agent as MCP resources. Nothing runs without `GEMINI_API_KEY` — sort that out first.

Auth is switched with `NANOBANANA_AUTH_METHOD`. The `api_key` path uses a Gemini key; `vertex_ai` goes through Google Cloud Application Default Credentials and needs `GCP_PROJECT_ID` and `GCP_REGION`. Set the region to `global` for Gemini 3 Pro Image and NB2 — `us-central1` only works with the legacy 2.5 Flash Image model. The `auto` mode tries the key first, then Vertex AI. Running from source requires Python 3.11+.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `GEMINI_API_KEY`, `IMAGE_OUTPUT_DIR` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env GEMINI_API_KEY=<GEMINI_API_KEY> --env IMAGE_OUTPUT_DIR=<IMAGE_OUTPUT_DIR> --transport stdio nanobanana-mcp-server -- uvx nanobanana-mcp-server
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from nanobanana-mcp-server <command>

### Codex

**Platform CLI**
```bash
codex mcp add nanobanana-mcp-server --env GEMINI_API_KEY=<GEMINI_API_KEY> --env IMAGE_OUTPUT_DIR=<IMAGE_OUTPUT_DIR> -- uvx nanobanana-mcp-server
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from nanobanana-mcp-server <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "nanobanana-mcp-server": {
            "command": "uvx",
            "args": [
                "nanobanana-mcp-server"
            ],
            "env": {
                "GEMINI_API_KEY": "<GEMINI_API_KEY>",
                "IMAGE_OUTPUT_DIR": "<IMAGE_OUTPUT_DIR>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from nanobanana-mcp-server <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "nanobanana-mcp-server": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "nanobanana-mcp-server"
            ],
            "env": {
                "GEMINI_API_KEY": "<GEMINI_API_KEY>",
                "IMAGE_OUTPUT_DIR": "<IMAGE_OUTPUT_DIR>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from nanobanana-mcp-server <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e GEMINI_API_KEY=<GEMINI_API_KEY> -e IMAGE_OUTPUT_DIR=<IMAGE_OUTPUT_DIR> nanobanana-mcp-server uvx nanobanana-mcp-server
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from nanobanana-mcp-server <command>

## When to use it
- generate an illustration from a text description inside a session
- touch up an existing image without leaving the editor
- set the aspect ratio to match a layout
- start from a ready prompt template instead of writing one
- upload a file to the Gemini Files API and reference it

## Example prompts
- Generate an image of a cat in a hat, 16:9
- Edit `cover.png` and remove the background
- Upload `logo.png` and use it as a reference

## Similar
- [MCP Toolbox for Databases](https://affpapa.org/en/nevibecode/mcp/googleapis-mcp-toolbox-for-databases.md) — MCP server · ★ 16717
- [labelhead-artist-momentum](https://affpapa.org/en/nevibecode/mcp/labelhead-artist-momentum.md) — MCP server · ★ 107423
- [Agent Skills Search Server](https://affpapa.org/en/nevibecode/mcp/agent-skills-search-server.md) — MCP server · ★ 26559
- [Skyvern](https://affpapa.org/en/nevibecode/mcp/skyvern.md) — MCP server · ★ 23263
- [Nhost](https://affpapa.org/en/nevibecode/mcp/nhost.md) — MCP server · ★ 9366
- [PraisonAI](https://affpapa.org/en/nevibecode/mcp/praisonai.md) — MCP server · ★ 9289

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md