# 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)
```bash
# Install globally
npm install -g @lyalindotcom/nano-banana-mcp
# Run setup wizard
nano-banana setup
```
### Option 2: NPX (No Install)
```bash
# 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):
```bash
export GEMINI_API_KEY="your-api-key"
```
Gemini CLI configuration (`~/.gemini/settings.json`):
```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):
```json
{
"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
```bash
# 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:
```bash
cp .env.example .env
# Edit .env with your GEMINI_API_KEY
```
2) Build:
```bash
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:
```bash
# 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:
```javascript
{
"prompt": "A cyberpunk city at night with neon lights",
"outputPath": "./assets/backgrounds/city.png"
}
```
Image editing:
```javascript
{
"prompt": "Add a rainbow in the sky",
"images": [{ "data": "./photos/landscape.jpg" }],
"outputPath": "./photos/landscape-rainbow.jpg"
}
```
Batch generation:
```javascript
{
"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:
```bash
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
```bash
> 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
```bash
> 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
```bash
> 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](https://aistudio.google.com/apikey))
- **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](https://github.com/LyalinDotCom/nano-banana-mcp/blob/main/LICENSE) file for details
## 🙏 Acknowledgments
- Built with the [Model Context Protocol](https://modelcontextprotocol.io)
- Powered by [Gemini Flash 2.5](https://deepmind.google/technologies/gemini/)
- Inspired by the amazing MCP community
## 🔗 Links
- [GitHub Repository](https://github.com/LyalinDotCom/nano-banana-mcp)
- [Report Issues](https://github.com/LyalinDotCom/nano-banana-mcp/issues)
- [Gemini CLI](https://github.com/google-gemini/gemini-cli)
- [Codex CLI](https://github.com/openai/codex)
- [MCP Specification](https://modelcontextprotocol.io)
---
<p align="center">
Made with ❤️ and 🍌 by a Nano Banana fan
</p>
