Nano Banana is an MCP server that exposes Google Gemini Flash 2.5 Image Generation via a clean, focused interface. It is not a general multi‑model server — it is a thin wrapper around Gemini Flash 2.5 image generation only.

Generate, edit, and manipulate images using natural language via any MCP‑compatible client.

Works with any MCP‑compatible client. Below we document Gemini CLI (recommended) and a minimal generic MCP configuration.

• Text-to-Image Generation: Create images from text descriptions
• Image Editing: Modify existing images with text prompts
• Multi-Image Composition: Combine multiple images or transfer styles
• Batch Generation: Generate multiple variations at once

• Combine Images: Stitch images into panoramas, grids, or strips
• Transform Images: Resize, crop, rotate, flip, and flop
• Adjust Images: Blur, sharpen, grayscale, tint, brightness, saturation
• Composite Images: Layer images with blend modes and positioning
• Batch Processing: Apply operations to entire directories

• Smart Path Handling: Automatically creates directories and handles file paths
• Image Validation: Verify generated images are valid and meet size requirements
• Comprehensive Error Handling: Clear feedback on API errors, quota issues, and failures
• MCP Protocol: Works with any MCP-compatible AI client

# Install globally
npm install -g @lyalindotcom/nano-banana-mcp

# Run setup wizard
nano-banana setup

# Run on demand via NPX (no global install)
# Great for Gemini CLI and generic MCP config
npx -y -p @lyalindotcom/nano-banana-mcp nano-banana --version

Set your API key once in your shell (required):

export GEMINI_API_KEY="your-api-key"

Gemini CLI configuration (~/.gemini/settings.json):

{
  "mcpServers": {
    "nano-banana": {
      "command": "npx",
      "args": ["-y", "-p", "@lyalindotcom/nano-banana-mcp", "nano-banana-server"],
      "env": { "GEMINI_API_KEY": "${GEMINI_API_KEY}" },
      "timeout": 60000,
      "trust": true
    }
  }
}

Generic MCP configuration (for other clients using stdio):

{
  "mcpServers": {
    "nano-banana": {
      "command": "npx",
      "args": ["-y", "-p", "@lyalindotcom/nano-banana-mcp", "nano-banana-server"],
      "env": { "GEMINI_API_KEY": "${GEMINI_API_KEY}" }
    }
  }
}

# Clone the repo
git clone https://github.com/LyalinDotCom/nano-banana-mcp.git
cd nano-banana-mcp

# Run the quickstart script - it does EVERYTHING!
./quickstart.sh

# That's it! Start using it:
gemini chat
> "Create a robot holding a banana at ./robot.png"

The quickstart script will:

• ✅ Check Node.js version
• ✅ Install Gemini CLI if needed
• ✅ Build the project
• ✅ Configure your API key
• ✅ Set up Gemini CLI integration
• ✅ Verify everything works

1. Configure API key:

cp .env.example .env
# Edit .env with your GEMINI_API_KEY

2. Build:

npm run build

3. Configure Gemini CLI using the JSON shown above.

Get your API key from: https://aistudio.google.com/apikey

The Nano Banana CLI provides powerful management tools:

# Interactive setup wizard (configures Gemini CLI integration)
nano-banana setup

# Create .env file with API key (does NOT configure Gemini CLI)
nano-banana init --api-key YOUR_KEY

# Start the MCP server directly (for manual testing)
nano-banana serve

# Check installation status
nano-banana status

# Diagnose any issues
nano-banana doctor

# Safely remove configuration
nano-banana remove

Important: Use setup to configure with Gemini CLI. The init command only creates a .env file.

Once configured, use with your MCP client of choice. Simply describe what you want:

• "Generate a cyberpunk city at ./city.png"
• "Create 5 potion icons at ./items/potions.png"
• "Add a sunset to ./photo.jpg"
• "Combine these images into a panorama"

• 🎨 Full Gemini Flash 2.5 Power: Access the latest image generation capabilities
• 🚀 Natural Language Interface: Just describe what you want
• 🔧 Flexible Integration: Works with Gemini CLI and other MCP clients
• 📁 Direct File Management: Images save exactly where you need them
• 🎯 Smart Context: One tool handles generation, editing, and composition
• ⚡ Batch Operations: Generate up to 10 variations at once

This README contains the supported setup paths. Nano Banana targets the Gemini Flash 2.5 image generation model only.

Generate, edit, or compose images using Gemini Flash 2.5.

Parameters:

• prompt (optional): Text description for generation
• images (optional): Array of input images (base64 or file paths)
• outputPath: Where to save the generated image(s)
• count (optional): Number of variations to generate (1-10)
• options (optional): Additional Gemini model options

Examples:

Text-to-image:

{
  "prompt": "A cyberpunk city at night with neon lights",
  "outputPath": "./assets/backgrounds/city.png"
}

Image editing:

{
  "prompt": "Add a rainbow in the sky",
  "images": [{ "data": "./photos/landscape.jpg" }],
  "outputPath": "./photos/landscape-rainbow.jpg"
}

Batch generation:

{
  "prompt": "Fantasy potion bottles, different colors",
  "outputPath": "./items/potion.png",
  "count": 5
}

Check if an image file exists and is valid.

Parameters:

• path: File path to validate

Returns:

• exists: Whether the file exists
• valid: Whether it's a valid image
• dimensions: Image width and height
• format: Image format (png, jpeg, etc.)
• fileSize: File size in bytes
• error: Error message if validation failed

1. Flexible Input: The server intelligently determines the operation mode:

   • Text only → Text-to-image generation
   • Text + 1 image → Image editing
   • Text + multiple images → Composition/style transfer

2. Path Management: Automatically creates directories and handles both absolute and relative paths

3. Batch Support: When count > 1, generates multiple variations with numbered suffixes

4. Validation: Uses Sharp to verify images are properly generated and meet minimum size requirements

5. No Overwrites: The server never overwrites existing files. If the requested outputPath (or any batch variation path) already exists, the server returns an error and does not write. Choose a new path or remove the file before retrying.

The server provides detailed error information:

• INVALID_API_KEY: Authentication failed
• QUOTA_EXCEEDED: API limits reached
• API_ERROR: General API failure
• INVALID_INPUT: Bad parameters
• FILE_WRITE_ERROR: Cannot save to path
• VALIDATION_FAILED: Image corrupt or too small
• FILE_EXISTS: Output file already exists; choose a new path

Run the example test script:

npm run dev examples/test.ts

This will test:

• Basic text-to-image generation
• Image validation
• Batch generation

nano-banana-mcp/
├── src/
│   ├── index.ts          # MCP server entry point
│   ├── tools.ts          # Tool implementations
│   └── gemini-client.ts  # Gemini API wrapper
├── examples/
│   └── test.ts           # Example usage
├── .env.example          # Environment template
└── README.md             # This file

> Generate a complete set of 16-bit RPG sprites: warrior, mage, archer at ./sprites/
> Create terrain tiles for a top-down game: grass, stone, water at ./tiles/
> Design UI elements: health bars, mana bars, inventory slots at ./ui/

> Create a hero section background with gradients at ./public/hero.jpg
> Generate a set of feature icons for my SaaS landing page at ./icons/
> Design social media cards for my blog posts at ./social/

> Generate YouTube thumbnail about "AI Revolution" at ./thumbnails/ai.jpg
> Create Instagram carousel about productivity tips at ./instagram/
> Design presentation diagrams for cloud architecture at ./slides/

• Node.js 18 or higher
• Gemini API Key with image generation access (Get one here)
• TypeScript 5.0+ (for development)

This is an experimental sample project. While GitHub issues are welcome for bug reports and feedback, this project is not actively seeking contributions and long-term maintenance is not guaranteed at this time.

MIT License - see LICENSE file for details

• Built with the Model Context Protocol
• Powered by Gemini Flash 2.5
• Inspired by the amazing MCP community

• GitHub Repository
• Report Issues
• Gemini CLI
• Codex CLI
• MCP Specification

Made with ❤️ and 🍌 by a Nano Banana fan