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 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.

Codex CLI:

Opencode CLI:

1. Run opencode config edit (or open your opencode.jsonc settings file manually).

2. Register the server with an entry similar to:

   { "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):

2. Build the server:

3. Register with your CLI:

For Codex CLI:

🔑 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:

   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:

Edit Images:

Restore Images:

Generate Icons:

Create Patterns:

Generate Stories:

Create Diagrams:

🌟 Natural Language Command (Flexible)

Open-ended prompts:

🎨 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:

Multiple Variations:

🎯 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

🎨 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

📖 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

📊 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

📁 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

MCP Server Commands

Tests

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:

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:

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: 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

🤝 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