mcp-nano-banana

mcp-nano-banana

MCP server for AI-powered image generation using Google Gemini Nano Banana models. Generate, edit, and combine images from text prompts — directly from your AI coding assistant.

!npm version !license

Features

• Text-to-image generation — Create images from natural language descriptions
• Image editing — Upload images and modify them with text instructions
• Multi-image combination — Mix up to 14 reference images into one composite
• Resolution control — Generate at 512px, 1K, 2K, or 4K resolution
• 13+ aspect ratios — From square (1:1) to ultra-wide (21:9) and tall (1:8)
• Auto-fallback — Pro model falls back to Flash on rate limits (429/403/402)
• File output — Save to specific paths or return inline base64
• Favicon generation — Generate complete favicon packages with one command
• Multi-format output — PNG, JPEG, and WebP support

Quick Start

Prerequisites

1. Get a Gemini API key from Google AI Studio
2. Enable billing on your Google Cloud project — image generation requires a paid tier (~$0.04-0.05/image for NB2 at standard resolution)

Installation

npm install -g mcp-nano-banana

Set your API key:

export GEMINI_API_KEY=your-api-key

For MCP Registry publication metadata, the registry name is io.github.codeFi/mcp-nano-banana.

MCP Configuration

Codex

codex mcp add nano-banana --env GEMINI_API_KEY=your-api-key -- npx -y mcp-nano-banana@latest

Or add manually to ~/.codex/config.toml:

[mcp_servers.nano-banana]
command = "npx"
args = ["-y", "mcp-nano-banana@latest"]

[mcp_servers.nano-banana.env]
GEMINI_API_KEY = "your-api-key"

Qwen Code

Add to ~/.qwen/settings.json:

{
  "mcpServers": {
    "nano-banana": {
      "command": "npx",
      "args": ["-y", "mcp-nano-banana@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

claude mcp add nano-banana -e GEMINI_API_KEY=your-api-key -- npx -y mcp-nano-banana@latest

Or add manually to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "nano-banana": {
      "command": "npx",
      "args": ["-y", "mcp-nano-banana@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Other MCP Clients

For CLIs and desktop clients that use the standard mcpServers JSON format, register:

{
  "mcpServers": {
    "nano-banana": {
      "command": "npx",
      "args": ["-y", "mcp-nano-banana@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Local / Development Build

git clone https://github.com/codeFi/mcp-nano-banana.git
cd mcp-nano-banana
npm install
npm run build

Then register with your MCP client:

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

Models

| Model | MCP Name | Description | Max Ref Images | |-------|----------|-------------|----------------| | gemini-3-pro-image-preview | Nano Banana Pro | High quality, thinking mode, professional assets | 6 object + 5 character | | gemini-3.1-flash-image-preview | Nano Banana 2 | Fast, high-efficiency, 1:4/4:1/1:8/8:1 ratios | 10 object + 4 character | | gemini-2.5-flash-image | Nano Banana | Fastest, optimized for high-volume tasks | - |

The server defaults to Nano Banana Pro for best quality and automatically falls back to Flash on rate limits.

Available Parameters

Resolution

| Value | Approx. Pixels | Supported Models | |-------|---------------|------------------| | "512" | ~512px | Nano Banana 2 only | | "1K" | ~1024px | All models | | "2K" | ~2048px | All models | | "4K" | ~4096px | All models |

Default: "1K"

Aspect Ratio

| Value | Dimensions at 1K | Common Use Case | |-------|-----------------|-----------------| | 1:1 | 1024×1024 | Social posts, icons | | 16:9 | 1344×768 | Headers, presentations | | 9:16 | 768×1344 | Stories, mobile | | 4:3 | 1152×896 | Desktop, photos | | 3:4 | 896×1152 | Portraits | | 2:3 | ~896×1344 | Print, magazines | | 3:2 | ~1344×896 | Photos | | 4:5 | ~896×1120 | Instagram posts | | 5:4 | ~1120×896 | Instagram landscape | | 21:9 | ~2048×878 | Ultra-wide banners | | 1:4 | ~512×2048 | Nano Banana 2 only — tall strips | | 4:1 | ~2048×512 | Nano Banana 2 only — wide strips | | 1:8 | ~512×4096 | Nano Banana 2 only — extra tall | | 8:1 | ~4096×512 | Nano Banana 2 only — extra wide |

Tools

generate_image

Generate or edit images from text prompts.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | prompt | string | ✅ Yes | — | Text description or editing instructions | | imagePaths | string[] | No | — | Reference image paths on disk (up to 14) | | model | string | No | gemini-3-pro-image-preview | Model to use | | aspectRatio | string | No | 1:1 | See table above for all options | | resolution | string | No | 1K | 512, 1K, 2K, or 4K | | outputFormat | string | No | png | png, jpeg, webp | | outputPath | string | No | — | Save image to this file path |

Examples

Generate from text: ``json { "prompt": "A sunset over mountains with dramatic lighting", "aspectRatio": "16:9", "resolution": "2K", "outputPath": "/Users/currentUser/Desktop/sunset.png" } ``

Edit an existing image: ``json { "prompt": "Change the background to a coffee shop interior", "imagePaths": ["/Users/currentUser/photo.jpg"], "outputPath": "/Users/currentUser/edited.png" } ``

Combine multiple images: ``json { "prompt": "Put these glasses on this person's face", "imagePaths": ["/path/to/face.jpg", "/path/to/glasses.jpg"], "outputPath": "/path/to/result.png" } ``

High-res wallpaper: ``json { "prompt": "A futuristic cityscape at night with neon lights and rain", "aspectRatio": "16:9", "resolution": "4K", "outputPath": "/path/to/wallpaper.png" } ``

generate_favicons

Generate a complete favicon package from a prompt or existing image.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | prompt | string | No\ | — | Icon description (required if imagePath not set) | | imagePath | string | No\ | — | Path to existing master icon image | | model | string | No | gemini-3-pro-image-preview | Model for prompt generation | | outputDir | string | No | — | Directory for individual favicon files | | outputPath | string | No | — | Save ZIP package to this path | | returnZipBase64 | boolean | No | false | Return ZIP as base64 text | | appName | string | No | My App | Manifest name | | shortName | string | No | App | Manifest short_name | | themeColor | string | No | #ffffff | Manifest theme color | | backgroundColor | string | No | #ffffff | Manifest background color | | includeReadme | boolean | No | true | Include README.md in package |

Example

{
  "prompt": "A minimalist banana icon with a soft gradient",
  "outputDir": "/path/to/favicon",
  "outputPath": "/path/to/favicon.zip",
  "appName": "MyBrand",
  "shortName": "Brand",
  "themeColor": "#1a1a2e",
  "backgroundColor": "#ffffff"
}

Generated files:

• favicon.ico — Multi-size icon (16/32/48px)
• favicon-16x16.png — Browser tabs
• favicon-32x32.png — Higher-res tabs
• apple-touch-icon.png — iOS home screen
• android-chrome-192x192.png — Android
• android-chrome-512x512.png — Android HD
• site.webmanifest — PWA manifest

HTML snippet (included in response): ``html <link rel="icon" href="/favicon.ico" sizes="any"> <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png"> <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png"> <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png"> <link rel="manifest" href="/site.webmanifest"> ``

Pricing

Image generation requires a paid Google AI Studio account. Approximate costs:

| Model | 1K | 2K | 4K | |-------|-----|-----|-----| | Nano Banana 2 | ~$0.04 | ~$0.08 | ~$0.15 | | Nano Banana Pro | ~$0.06 | ~$0.13 | ~$0.24 |

You only pay for what you generate — no monthly minimum.

Supported Image Formats

Input (reference images): png, jpg, jpeg, webp, gif Output: png, jpeg, webp

Development

# Build TypeScript
npm run build

# Watch mode
npm run dev

# Run tests
npm test

# Run the server directly
node dist/index.js

Troubleshooting

| Issue | Solution | |-------|----------| | GEMINI_API_KEY is not set | Export the env var or add it to your MCP config | | 429 Too Many Requests | Server auto-falls back to Flash model. Add billing to your account. | | 403/402 Quota exceeded | Enable billing at Google Cloud Console | | 503 Unavailable | High demand — retry in a moment. Common with 4K requests. | | Image not updating after edit | Make sure you rebuilt the TypeScript (npm run build) | | imagePaths not found | Use absolute paths. Relative paths may not resolve correctly. |

Architecture

AI Assistant (MCP Client)
       │  (MCP Protocol over stdio)
       ▼
mcp-nano-banana Server
       │  (HTTPS POST)
       ▼
Google Gemini API
       │
       ▼
Generated Image → saved to outputPath (or returned inline base64)

License

MIT

Author

codeFi