MCP Nanobanana

🚀 Nano Banana - MCP Image Generation Extension

Nano Banana is a professional MCP (Model Context Protocol) extension designed for all MCP-compatible clients, such as Gemini CLI and Codex CLI. It empowers users to generate and manipulate images effortlessly. By default, it leverages the google/gemini-2.5-flash-image model and is pre-configured to connect to OpenRouter. You can switch to other providers hosting the model by adjusting the MODEL_* environment variables.

✨ Features

• 🎨 Text-to-Image Generation: Craft captivating images from descriptive text prompts.
• ✏️ Image Editing: Modify existing images using natural language instructions.
• 🔧 Image Restoration: Restore and enhance old or damaged photos.
• 📁 Smart File Management: Enjoy user-friendly filenames with automatic duplicate prevention.

📋 Prerequisites

1. MCP-compatible CLI: Install and configure an MCP-compatible CLI, like Gemini CLI or Codex CLI.
2. Node.js 18+ and npm: Ensure you have Node.js version 18 or higher and npm installed.
3. API Key: Obtain an API key from OpenRouter or another provider hosting the google/gemini-2.5-flash-image model.

By default, the extension communicates with OpenRouter. You can use the following optional overrides when targeting other providers:

• MODEL_BASE_URL: Alternate provider endpoint (default: https://openrouter.ai/api/v1).
• MODEL_ID: Override the model ID (default: google/gemini-2.5-flash-image).
• MODEL_REFERER / MODEL_TITLE: Analytics headers required by some providers.
• MODEL_GENERATE_PATH: Alternate generation endpoint path (default: /responses).

If you're using OpenRouter, refer to their authentication guide for API key generation. For other providers, consult their documentation.

🚀 Quick Start

📦 Installation

From NPM (Recommended)

For most users, installing via npx or your CLI's extension manager is the simplest approach.

Gemini CLI: During the installation process, you'll be prompted to enter your API key.

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

Codex CLI:

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 manually open your opencode.jsonc settings file.
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 to apply the new MCP server configuration.

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 with your provider key.
4. Save the server configuration and restart Claude Code (or reload the window) to establish the connection.

For Local Development

If you've cloned this repository for development, you can register your local version.

1. Install server dependencies (once per clone):

npm run install-deps

2. Build the server:

npm run build

3. Register with your CLI:

For Codex CLI:

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'll be automatically prompted to enter your API key during the installation process.

Codex CLI

The codex mcp add command includes a dedicated --env flag for this purpose. The installation command provided above already incorporates this and is the recommended method.

Other CLIs (Shell Profile)

For other clients or if you prefer manual key management, 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 changes to take effect.

Activate

Restart your MCP CLI (e.g., Gemini CLI, Codex CLI). The following commands will become available:

• /generate: Generate single or multiple images with style and variation options.
• /edit: Edit existing images.
• /restore: Restore images.
• /icon: Generate app icons, favicons, and UI elements in multiple sizes.
• /pattern: Generate seamless patterns and textures for backgrounds.
• /story: Generate sequential images for visual storytelling or process demonstration.
• /diagram: Generate technical diagrams, flowcharts, and architectural mockups.
• /nanobanana: Natural language interface.

💻 Usage Examples

🎯 Specific Commands (Recommended)

Generate Images

# 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

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

Restore Images

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

Generate Icons

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

Create Patterns

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

Generate Stories

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

Create Diagrams

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

🌟 Natural Language Command (Flexible)

/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

Generation Options

Available Styles

Available Variations

Advanced Examples

Style Variations

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

Multiple Variations

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

🎯 Icon Generation

Icon Options

Icon Examples

# 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

Pattern Options

Pattern Examples

# 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

Story Options

Story Examples

# 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

Diagram Options

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

# 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. For example:

• "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. For example:

• sunset_over_mountains.png
• sunset_over_mountains_1.png
• sunset_over_mountains_2.png

File Search Locations

For editing and restoration, the extension searches for input images in the following locations:

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

# 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

# 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

# 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 test the real OpenRouter workflow end-to-end, run the manual script after setting MODEL_API_KEY:

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 ensure the published npm binary boots correctly:

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. You can safely 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 reliable 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 that 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've entered the API key correctly during installation or that the MODEL_API_KEY environment variable is set correctly if not using Gemini CLI.
3. "Build failed": Make sure 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 in your CLI console (Gemini CLI, Codex CLI, etc.) to assist with issue diagnosis.

📄 License

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