# Nano Banana - MCP Image Generation Extension

A professional MCP (Model Context Protocol) extension for any MCP-compatible client (including Gemini CLI and Codex CLI), for generating and manipulating images. It uses the **google/gemini-2.5-flash-image** model by default, and is pre-configured to connect to OpenRouter. You can point it at any provider that hosts the model by adjusting the `MODEL_*` environment variables.

## ✨ Features

- **🎨 Text-to-Image Generation**: Create stunning images from descriptive prompts
- **✏️ Image Editing**: Modify existing images with natural language instructions
- **🔧 Image Restoration**: Restore and enhance old or damaged photos
- **📁 Smart File Management**: User-friendly filenames with automatic duplicate prevention

## 📋 Prerequisites

1.  **MCP-compatible CLI** installed and configured (e.g., Gemini CLI, Codex CLI)
2.  **Node.js 18+** and npm
3.  **API Key**: You will need an API key from OpenRouter or another provider that hosts the `google/gemini-2.5-flash-image` model.

By default, the extension talks to OpenRouter. Optional overrides are useful when targeting other providers that host the model:

- `MODEL_BASE_URL` – alternate provider endpoint (default: `https://openrouter.ai/api/v1`)
- `MODEL_ID` – override model id (default: `google/gemini-2.5-flash-image`)
- `MODEL_REFERER` / `MODEL_TITLE` – analytics headers for providers that require them
- `MODEL_GENERATE_PATH` – alternate generation endpoint path (default: `/responses`)

If you are using OpenRouter, refer to their [authentication guide](https://openrouter.ai/docs#authenticate) for generating API keys. For other providers, consult their documentation.

## 🚀 Installation

### From NPM (Recommended)

For most users, installing via `npx` or your CLI's extension manager is the easiest method.

**Gemini CLI:**

When you install the extension, you will be prompted to enter your API key.

```bash
gemini extensions install https://github.com/Aeven-AI/mcp-nanobanana
```

**Codex CLI:**

```bash
codex mcp add nanobanana --env MODEL_API_KEY="YOUR_API_KEY_HERE" -- npx -y @aeven/nanobanana-mcp@latest
```

**Opencode CLI:**

1.  Run `opencode config edit` (or open your `opencode.jsonc` settings file manually).
2.  Register the server with an entry similar to:

    ```jsonc
    {
      "mcp": {
        "nanobanana": {
          "type": "local",
          "command": ["npx", "-y", "@aeven/nanobanana-mcp@latest"],
          "enabled": true,
          "environment": {
            "MODEL_API_KEY": "{env:MODEL_API_KEY}"
          }
        }
      }
    }
    ```

3.  Save the file and restart Opencode so it picks up the new MCP server.

**Claude Code:**

1.  Open Claude Code and navigate to **Settings → Model Context Protocol → Add Server**.
2.  Set the command to `npx` and the arguments to `-y` and `@aeven/nanobanana-mcp@latest`.
3.  Add an environment variable `MODEL_API_KEY` pointing at your provider key.
4.  Save the server configuration and restart Claude Code (or reload the window) to connect.

### For Local Development

If you have cloned this repository to work on the code, you can register your local version.

**1. Install server dependencies (once per clone):**

```bash
npm run install-deps
```

**2. Build the server:**

```bash
npm run build
```

**3. Register with your CLI:**



**For Codex CLI:**

```bash

codex mcp add nanobanana --env MODEL_API_KEY="YOUR_API_KEY_HERE" -- node mcp-server/dist/index.js

```





## 🔑 API Key Configuration

This extension requires a `MODEL_API_KEY` to authenticate with your model provider (e.g., OpenRouter). Here’s how to configure it for different clients:

### Gemini CLI

You will be prompted to enter your API key automatically during the installation process.

### Codex CLI

The `codex mcp add` command has a dedicated `--env` flag to handle this for you. The command provided in the "Installation" section already includes this and is the recommended way to install.

### Other CLIs (Shell Profile)

For other clients, or if you prefer to manage the key manually, you can set the `MODEL_API_KEY` as an environment variable in your shell's profile file (e.g., `~/.zshrc`, `~/.bashrc`, or `~/.profile`).

1.  Add the following line to the end of the file:
    ```bash
    export MODEL_API_KEY="YOUR_API_KEY_HERE"
    ```
2.  Restart your terminal for the change to take effect.

### Activate

Restart your MCP CLI (Gemini CLI, Codex CLI, etc.). The following commands will be available:

- `/generate` - Single or multiple image generation with style/variation options
- `/edit` - Image editing
- `/restore` - Image restoration
- `/icon` - Generate app icons, favicons, and UI elements in multiple sizes
- `/pattern` - Generate seamless patterns and textures for backgrounds
- `/story` - Generate sequential images that tell a visual story or process
- `/diagram` - Generate technical diagrams, flowcharts, and architectural mockups
- `/nanobanana` - Natural language interface

## 💡 Usage

The extension provides multiple command options for different use cases:

> **Note:** Examples below use Gemini CLI slash commands. In Codex CLI and other MCP clients, call the same MCP tools (`generate_image`, `edit_image`, etc.) using the syntax your client provides.

### 🎯 Specific Commands (Recommended)

**Generate Images:**

```bash
# Single image
/generate "a watercolor painting of a fox in a snowy forest"

# Multiple variations with preview
/generate "sunset over mountains" --count=3 --preview
```

**Edit Images:**

```bash
/edit my_photo.png "add sunglasses to the person"
/edit portrait.jpg "change background to a beach scene" --preview
```

**Restore Images:**

```bash
/restore old_family_photo.jpg "remove scratches and improve clarity"
```

**Generate Icons:**

```bash
/icon "coffee cup logo" --sizes="64,128,256" --type="app-icon" --preview
```

**Create Patterns:**

```bash
/pattern "geometric triangles" --type="seamless" --style="geometric" --preview
```

**Generate Stories:**

```bash
/story "a seed growing into a tree" --steps=4 --type="process" --preview
```

**Create Diagrams:**

```bash
/diagram "user login process" --type="flowchart" --style="professional" --preview
```

### 🌟 Natural Language Command (Flexible)

**Open-ended prompts:**

```bash
/nanobanana create a logo for my tech startup
/nanobanana I need 5 different versions of a cat illustration in various art styles
/nanobanana fix the lighting in sunset.jpg and make it more vibrant
```

## 🎨 Advanced Generation Options

The `/generate` command supports advanced options for creating multiple variations with different styles and parameters.

\<details\>
\<summary\>Generation Options\</summary\>

**`--count=N`** - Number of variations (1-8, default: 1)
**`--styles="style1,style2"`** - Comma-separated artistic styles
**`--variations="var1,var2"`** - Specific variation types
**`--format=grid|separate`** - Output format (default: separate)
**`--seed=123`** - Seed for reproducible variations
**`--preview`** - Automatically open generated images in default viewer

\</details\>

\<details\>
\<summary\>Available Styles\</summary\>

- `photorealistic` - Photographic quality images
- `watercolor` - Watercolor painting style
- `oil-painting` - Oil painting technique
- `sketch` - Hand-drawn sketch style
- `pixel-art` - Retro pixel art style
- `anime` - Anime/manga art style
- `vintage` - Vintage/retro aesthetic
- `modern` - Contemporary/modern style
- `abstract` - Abstract art style
- `minimalist` - Clean, minimal design

\</details\>

\<details\>
\<summary\>Available Variations\</summary\>

- `lighting` - Different lighting conditions (dramatic, soft)
- `angle` - Various viewing angles (above, close-up)
- `color-palette` - Different color schemes (warm, cool)
- `composition` - Different layouts (centered, rule-of-thirds)
- `mood` - Various emotional tones (cheerful, dramatic)
- `season` - Different seasons (spring, winter)
- `time-of-day` - Different times (sunrise, sunset)

\</details\>

### Advanced Examples

**Style Variations:**

```bash
/generate "mountain landscape" --styles="watercolor,oil-painting,sketch,photorealistic"
# Creates the same mountain scene in 4 different artistic styles
```

**Multiple Variations:**

```bash
/generate "cozy coffee shop" --variations="lighting,mood" --count=4
# Generates: dramatic lighting, soft lighting, cheerful mood, dramatic mood versions
```

## 🎯 Icon Generation

The `/icon` command specializes in creating app icons, favicons, and UI elements with proper sizing and formatting.

\<details\>
\<summary\>Icon Options\</summary\>

**`--sizes="16,32,64"`** - Array of icon sizes in pixels (common: 16, 32, 64, 128, 256, 512, 1024)
**`--type="app-icon|favicon|ui-element"`** - Icon type (default: app-icon)
**`--style="flat|skeuomorphic|minimal|modern"`** - Visual style (default: modern)
**`--format="png|jpeg"`** - Output format (default: png)
**`--background="transparent|white|black|color"`** - Background type (default: transparent)
**`--corners="rounded|sharp"`** - Corner style for app icons (default: rounded)

\</details\>

### Icon Examples

```bash
# Complete app icon set
/icon "productivity app with checklist" --sizes="64,128,256,512" --corners="rounded"

# Website favicon package
/icon "mountain logo" --type="favicon" --sizes="16,32,64" --format="png"
```

## 🎨 Pattern & Texture Generation

The `/pattern` command creates seamless patterns and textures perfect for backgrounds and design elements.

\<details\>
\<summary\>Pattern Options\</summary\>

**`--size="256x256"`** - Pattern tile size (common: 128x128, 256x256, 512x512)
**`--type="seamless|texture|wallpaper"`** - Pattern type (default: seamless)
**`--style="geometric|organic|abstract|floral|tech"`** - Pattern style (default: abstract)
**`--density="sparse|medium|dense"`** - Element density (default: medium)
**`--colors="mono|duotone|colorful"`** - Color scheme (default: colorful)
**`--repeat="tile|mirror"`** - Tiling method for seamless patterns (default: tile)

\</details\>

### Pattern Examples

```bash
# Website background pattern
/pattern "subtle geometric hexagons" --type="seamless" --colors="duotone" --density="sparse"

# Material texture
/pattern "brushed metal surface" --type="texture" --style="tech" --colors="mono"
```

## 📖 Visual Storytelling

The `/story` command generates sequential images that tell a visual story or demonstrate a step-by-step process.

\<details\>
\<summary\>Story Options\</summary\>

**`--steps=N`** - Number of sequential images (2-8, default: 4)
**`--type="story|process|tutorial|timeline"`** - Sequence type (default: story)
**`--style="consistent|evolving"`** - Visual consistency across frames (default: consistent)
**`--layout="separate|grid|comic"`** - Output layout (default: separate)
**`--transition="smooth|dramatic|fade"`** - Transition style between steps (default: smooth)
**`--format="storyboard|individual"`** - Output format (default: individual)

\</details\>

### Story Examples

```bash
# Product development process
/story "idea to launched product" --steps=5 --type="process" --style="consistent"

# Educational tutorial
/story "git workflow tutorial" --steps=6 --type="tutorial" --layout="comic"
```

## 📊 Technical Diagrams

The `/diagram` command generates professional technical diagrams, flowcharts, and architectural mockups from simple text descriptions.

\<details\>
\<summary\>Diagram Options\</summary\>

**`--type="flowchart|architecture|network|database|wireframe|mindmap|sequence"`** - Diagram type (default: flowchart)
**`--style="professional|clean|hand-drawn|technical"`** - Visual style (default: professional)
**`--layout="horizontal|vertical|hierarchical|circular"`** - Layout orientation (default: hierarchical)
**`--complexity="simple|detailed|comprehensive"`** - Level of detail (default: detailed)
**`--colors="mono|accent|categorical"`** - Color scheme (default: accent)
**`--annotations="minimal|detailed"`** - Label and annotation level (default: detailed)

\</details\>

### Diagram Types & Use Cases

- **flowchart**: Process flows, decision trees, workflows
- **architecture**: System architecture, microservices, infrastructure
- **network**: Network topology, server configurations
- **database**: Database schemas, entity relationships
- **wireframe**: UI/UX mockups, page layouts
- **mindmap**: Concept maps, idea hierarchies
- **sequence**: Sequence diagrams, API interactions

### Diagram Examples

```bash
# Development workflow
/diagram "CI/CD pipeline with testing stages" --type="flowchart" --complexity="detailed"

# System design
/diagram "chat application architecture" --type="architecture" --style="technical"
```

## 📁 File Management

### Smart Filename Generation

Images are saved with user-friendly names based on your prompts:

- `"sunset over mountains"` → `sunset_over_mountains.png`
- `"abstract art piece"` → `abstract_art_piece.png`

### Automatic Duplicate Prevention

If a file already exists, a counter is automatically added:

- `sunset_over_mountains.png`
- `sunset_over_mountains_1.png`
- `sunset_over_mountains_2.png`

### File Search Locations

For editing/restoration, the extension searches for input images in:

1.  Current working directory
2.  `./images/` subdirectory
3.  `./input/` subdirectory
4.  `./nanobanana-output/` subdirectory
5.  `~/Downloads/`
6.  `~/Desktop/`

### Output Directory

Generated images are saved to `./nanobanana-output/` which is created automatically.

## 🛠️ Development

### Build Commands

```bash
# Build the MCP server
npm run build

# Install MCP server dependencies
npm run install-deps

# Development mode with file watching
npm run dev
```

### MCP Server Commands

```bash
# Build MCP server directly
cd mcp-server && npm run build

# Start server standalone (for testing)
cd mcp-server && npm start

# Development mode with TypeScript watching
cd mcp-server && npm run dev
```

### Tests

```bash
# Run the full suite (build + unit + integration)
cd mcp-server && npm test

# Only unit tests (FileHandler, ImageGenerator with mocked fetch)
cd mcp-server && npm run test:unit

# Only integration tests (in-memory MCP handshake with a stub image generator)
cd mcp-server && npm run test:integration
```

> The default integration test uses an in-memory transport and a stubbed image generator, so it runs offline and does not require an API key.

To exercise the real OpenRouter workflow end-to-end, run the manual script after setting `MODEL_API_KEY`:

```bash
cd mcp-server
MODEL_API_KEY="sk-..." node ./tests/manual/openrouter.integration.js
```

Generated assets are placed under `mcp-server/nanobanana-output/` for manual inspection.

### Verify npm packaging

Run the automated smoke test to make sure the published npm binary boots correctly:

```bash
npm run verify:npm
```

This command packs the project, installs the tarball in a temporary directory, launches `npx nanobanana-mcp`, and confirms the stdio server banner appears. It is safe to interrupt after the success message.

## 🔧 Technical Details

### Key Components

- **`index.ts`**: MCP server using `@modelcontextprotocol/sdk` for professional protocol handling
- **`imageGenerator.ts`**: Handles all OpenRouter API interactions and response processing
- **`fileHandler.ts`**: Manages file I/O, smart filename generation, and file searching
- **`types.ts`**: Shared TypeScript interfaces for type safety

### MCP Server Protocol

The extension uses the official Model Context Protocol (MCP) SDK for robust client-server communication:

- **Protocol**: JSON-RPC over stdio
- **SDK**: `@modelcontextprotocol/sdk`
- **Tools**: `generate_image`, `edit_image`, `restore_image`

### API Integration

- **Model**: `google/gemini-2.5-flash-image` (configurable via environment variable)
- **Transport**: Direct HTTP requests (OpenRouter by default; set `MODEL_BASE_URL` to target other providers hosting the model)
- **Response Handling**: Base64 decoding with graceful fallbacks for missing image data
- **Output Size**: All images are returned at 1024×1024 resolution (model maximum)

### Error Handling

- Comprehensive error messages with debugging information
- Graceful fallbacks for API response parsing
- File validation and search path reporting

## 🐛 Troubleshooting

### Common Issues

1.  **"Command not recognized"**: Verify the MCP server is registered for your CLI (e.g., `~/.gemini/extensions/nanobanana-extension/` for Gemini CLI, Codex CLI configuration for Codex users) and restart the client

2.  **"No API key found"**: Ensure you have entered the API key correctly when prompted during installation, or that the `MODEL_API_KEY` environment variable is set correctly if you are not using Gemini CLI.

3.  **"Build failed"**: Ensure Node.js 18+ is installed and run `npm run install-deps && npm run build`.

4.  **"Image not found"**: Check that input files are in one of the searched directories (see File Search Locations above)

5.  **`npx` install errors**: Stale directories in `~/.npm/_npx` can cause install failures. Remove the cache with `rm -rf ~/.npm/_npx/*` and rerun the install command.

### Debug Mode

The MCP server includes detailed debug logging that appears in your CLI console (Gemini CLI, Codex CLI, etc.) to help diagnose issues.

## 📄 Legal

- **License**: Apache License 2.0
- **Security**: [Security Policy](SECURITY.md)

## 🤝 Contributing

1.  Fork the repository
2.  Create a feature branch
3.  Make your changes in the modular architecture
4.  Run `npm run build` to ensure compilation
5.  Test with your MCP CLI (Gemini CLI, Codex CLI, etc.)
6.  Submit a pull request