nano-banana-claude

Generated by generate_image (Nano Banana flash, 16:9).

A small MCP server that gives Claude Code (or any MCP client) image generation via Google's Nano Banana Gemini image models — plus the deterministic post-processing the model can't do reliably on its own: true alpha transparency, AI upscaling, resizing, and format conversion.

The idea: keep generation in the model, but put the things that need real code (a genuine alpha channel, exact dimensions, super-resolution) behind tools so they're reliable instead of prompt-and-hope.

Tools

Tool	What it does
generate_image	Text → image. model (flash/pro), aspect_ratio, format, output_path.
generate_transparent_image	Generate, then remove the background with rembg (U2-Net) → a real RGBA PNG. Nano Banana can't produce reliable alpha on its own.
edit_image	One or more input images + a prompt → edited / composited result.
process_image	Local Pillow ops, no API call: resize/fit/crop, convert (png/webp/jpeg + quality), optional background removal.
upscale_image	AI super-resolution with Real-ESRGAN (realesr-general-x4v3). Tiled for large images, alpha-preserving.

Models: flash → gemini-2.5-flash-image (Nano Banana, default, fast/cheap), pro → gemini-3-pro-image-preview (Nano Banana Pro, higher quality).

Requirements

• Python 3.10+
• A Gemini API key (free tier available) from https://aistudio.google.com/apikey
• ~500 MB disk for dependencies; CPU is fine (no GPU required)

Install

git clone https://github.com/tougenrip/nano-banana-claude.git
cd nano-banana-claude
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

Two ML models download automatically on first use (not committed):

• rembg U2-Net (~176 MB) → ~/.u2net/ — first transparent-image call
• Real-ESRGAN x4 (~4.6 MB) → ~/.cache/nano-banana/ — first upscale call

Register with Claude Code

From inside the cloned directory:

claude mcp add nano-banana --scope user \
  --env GEMINI_API_KEY=your-key-here \
  -- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"

--scope user makes it available in every project; drop it to scope to the current project. Reconnect and the five nano-banana tools appear. The API key is read from the environment at runtime and is never written into the code.

Usage

Once registered, just ask in natural language — Claude picks the tool:

• "Generate a 16:9 image of a neon city at night." → generate_image
• "Make a transparent PNG of a red sneaker." → generate_transparent_image
• "Put the logo in photo.png onto the mug in mug.jpg." → edit_image
• "Resize hero.png to 1200px wide as webp." → process_image
• "Upscale icon.png 4×." → upscale_image

Tools can chain: generate a transparent cutout, then upscale it — the alpha survives.

Outputs are written next to the working directory (or to output_path) and the absolute path is returned. Set NANO_BANANA_OUTPUT_DIR to change the default location.

How transparency works

Image models paint pixels; asking for a "transparent background" usually yields a flat color or a drawn-in checkerboard, not a real alpha channel. So generate_transparent_image generates the subject on a plain background, then runs rembg (U2-Net) to compute an actual alpha matte, producing a true RGBA PNG. process_image(remove_background=true) does the same on any existing image.

<img src="examples/transparent-banana.png" alt="Transparent cutout example" width="320">

Output of generate_transparent_image — a real RGBA PNG (~90% of pixels fully transparent), not a painted-on checkerboard.

Layout

server.py          FastMCP server + tool definitions; Gemini REST via stdlib urllib
upscale.py         Real-ESRGAN inference (onnxruntime), lazily loaded, with tiling
requirements.txt   mcp, Pillow, rembg, onnxruntime

License

MIT — see LICENSE.