Nano Banana MCP Server

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.

✨ What It Does

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

🚀 Compatible Tools

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

Features

🎨 Image Generation (Powered by Gemini Flash 2.5)

• 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

🛠️ Image Manipulation (Powered by Sharp)

• 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

🔧 Developer Features

• 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

🚀 Quick Install (1 Minute!)

Option 1: Global Install (Recommended)

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

# Run setup wizard
nano-banana setup

Option 2: NPX (No Install)

# 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}" }
    }
  }
}

Option 3: From Source

# 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

Minimal Setup (from source)

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

CLI Commands

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.

Usage

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"

🌟 Why Nano Banana?

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

📚 Documentation

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

Available Tools

generate_image

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
}

validate_image

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

How It Works

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.

Error Handling

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

Testing

Run the example test script:

npm run dev examples/test.ts

This will test:

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

Project Structure

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

🎮 Real-World Use Cases

Game Development

> 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/

Web Development

> 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/

Content Creation

> 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/

🛠️ Requirements

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

🔧 Project Status

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.

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

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

🔗 Links

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