# nano-banana-mcp

A minimal [MCP](https://modelcontextprotocol.io) server that wraps Google Gemini image generation ("Nano Banana") for use inside Claude Code or any other MCP-compatible host.

Built as part of an exploration of agentic workflows for K-12 teaching materials. The whole server is about 75 lines of Python — readable in one sitting.

## What it does

Exposes a single tool:

```
generate_image(prompt: str, output_path: str, model: str | None = None) -> str
```

- Writes a PNG to `output_path`
- Auto-suffixes on collision (`foo.png` → `foo-1.png`, `foo-2.png`, …) — never silently overwrites
- Returns the absolute path it actually wrote to

## Install on a new machine

You need:

- [Homebrew](https://brew.sh) (macOS)
- A Gemini API key from [Google AI Studio](https://aistudio.google.com/apikey)
- [Claude Code](https://claude.com/claude-code) (or another MCP host)

```sh
brew install pipx
pipx ensurepath
pipx install git+https://github.com/DenialGelon/nano-banana-mcp

claude mcp add nano-banana --scope user \
  --env GEMINI_API_KEY=<your-key> -- nano-banana-mcp
```

Verify with `claude mcp list` — you should see `nano-banana: ✓ Connected`.

## Use

Start a fresh Claude Code session and ask:

> Generate an image of a friendly cartoon banana mascot and save it to ~/Desktop/banana.png

Claude will pick up the tool and call it. The return value tells you the final path (with a note if a collision was auto-resolved).

## Models

The `model` argument is optional. Known values (verified 2026-05-18 at the [Gemini image-generation docs](https://ai.google.dev/gemini-api/docs/image-generation)):

| Model string | Nickname | Use for |
|---|---|---|
| `gemini-2.5-flash-image` (default) | Nano Banana | Fast / cheap drafts |
| `gemini-3.1-flash-image-preview` | Nano Banana 2 | Higher quality, balanced |
| `gemini-3-pro-image-preview` | Nano Banana Pro | Top quality, costliest |

## Update / rotate the key

Update the code:

```sh
pipx install --force git+https://github.com/DenialGelon/nano-banana-mcp
```

Rotate the API key:

```sh
claude mcp remove nano-banana --scope user
claude mcp add nano-banana --scope user \
  --env GEMINI_API_KEY=<new-key> -- nano-banana-mcp
```

## License

MIT — see [LICENSE](LICENSE).