hz1ulqu01gmnZH4/nanobanana-mcp

Nano Banana MCP Server

MCP (Model Context Protocol) server for Nano Banana (Gemini 2.5 Flash Image Preview) - supporting both direct Gemini API and OpenRouter access for advanced image generation.

Features

• Dual Provider Support: Use either Google Gemini API directly or access via OpenRouter
• Text-to-Image Generation: Create images from detailed text descriptions
• Image-to-Image Generation: Transform existing images with text prompts
• Multi-Reference Support: Combine multiple reference images for complex transformations
• Scenario-Based Generation: Optimized prompts for specific use cases
• Aspect Ratio Control: Natural language control over image dimensions
• File Saving: Option to save generated images locally

Installation

npm install
npm run build

Configuration

For Claude Desktop

Add to your Claude Desktop configuration file:

Using Gemini API directly:

{
  "mcpServers": {
    "nanobanana": {
      "command": "node",
      "args": ["/path/to/nanobanana-mcp/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key"
      }
    }
  }
}

Using OpenRouter:

{
  "mcpServers": {
    "nanobanana": {
      "command": "node",
      "args": ["/path/to/nanobanana-mcp/dist/index.js"],
      "env": {
        "OPENROUTER_API_KEY": "your-openrouter-api-key"
      }
    }
  }
}

Using both providers:

{
  "mcpServers": {
    "nanobanana": {
      "command": "node",
      "args": ["/path/to/nanobanana-mcp/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key",
        "OPENROUTER_API_KEY": "your-openrouter-api-key"
      }
    }
  }
}

Getting API Keys

Gemini API Key

1. Go to Google AI Studio
2. Create a project or use existing one
3. Click "Get API key" to generate your key

OpenRouter API Key

1. Visit OpenRouter
2. Sign up or log in
3. Generate an API key from your dashboard

Reference Image Options

The MCP server supports three ways to provide reference images:

1. File Paths: Load images from local files

   images: [{ path: "./my-image.jpg" }]
   

2. URLs: Load images from the web

   images: [{ url: "https://example.com/image.jpg" }]
   

3. Base64: Provide pre-encoded image data

   images: [{ base64: "iVBORw0KGgo...", mimeType: "image/png" }]
   

Usage Examples

Basic Text-to-Image

generate_image({
  prompt: "A cyberpunk city at night with neon lights and flying cars"
})

Style Transfer with Reference Image

Using a URL:

generate_image({
  prompt: "Apply this artistic style to a photo of a mountain",
  images: [{
    url: "https://example.com/style-reference.jpg"
  }],
  scenario: "style-transfer"
})

Using a local file:

generate_image({
  prompt: "Apply this artistic style to a photo of a mountain",
  images: [{
    path: "./images/style-reference.jpg",
    description: "Artistic style reference"
  }],
  scenario: "style-transfer"
})

Character Design

generate_image({
  prompt: "A steampunk inventor character",
  scenario: "character-design",
  aspect_ratio: "16:9"
})

Multi-Reference Combination

You can mix different input types (URLs, file paths, and base64):

generate_image({
  prompt: "Combine the clothing style from the first image with the pose from the second",
  images: [
    { path: "./references/clothing.jpg" },
    { url: "https://example.com/pose.jpg" },
    { base64: "iVBORw0KGgo...", mimeType: "image/png" }
  ],
  scenario: "multi-reference"
})

With File Saving

generate_image({
  prompt: "A serene Japanese garden in autumn",
  save_to_file: true,
  filename: "japanese_garden",
  aspect_ratio: "landscape"
})

Available Scenarios

• text-to-image: Generate from text only
• style-transfer: Apply artistic styles
• character-design: Create character sheets
• pose-modification: Change poses while maintaining appearance
• background-expansion: Extend or modify backgrounds
• multi-reference: Combine multiple image elements
• cross-view: Generate different viewing angles
• ar-overlay: Add AR information overlays
• photo-enhancement: Improve photo quality

Tips for Best Results

1. Aspect Ratio Control: When aspect_ratio parameter is used, a blank canvas image is automatically added as the last image to control output dimensions (based on Zenn article technique)
2. How It Works: The model generates content to fill the blank canvas dimensions
3. Supported Ratios: square (1:1), landscape (16:9), portrait (9:16), widescreen (16:10), and custom ratios like 4:3
4. Reference Images: When using reference images with aspect ratio control, they are placed before the blank canvas
5. Detailed Prompts: Be specific and descriptive for best results

API Parameters

generate_image

Note: The Gemini 2.5 Flash Image Preview model uses natural language processing to interpret styling, composition, and generation instructions rather than structured API parameters.

Development

# Install dependencies
npm install

# Build
npm run build

# Run in development
npm run dev

License

WTFPL - Do What The Fuck You Want To Public License

Credits

Based on Nano Banana (Gemini 2.5 Flash Image Preview) capabilities as documented in:

• Awesome Nano Banana Images
• Google Gemini API Documentation