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

Get a Gemini API key from Google AI Studio
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:

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

Edit an existing image:

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

Combine multiple images:

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

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

<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