Content
# nanobanana-py
Python MCP Server, utilizing Google Gemini models for AI image generation.
Completely ported from [nanobanana](https://github.com/doggy8088/nanobanana) (TypeScript version).
## ✨ Features
- **🎨 Text-to-Image Generation**: Generate high-quality images based on descriptive prompts
- **✏️ Image Editing**: Modify existing images using natural language instructions
- **🔧 Image Restoration**: Restore and enhance old or damaged photos
- **🏷️ Icon Generation**: Generate multi-size app icons, favicons, and UI elements
- **🎯 Pattern Generation**: Create seamless patterns and background textures
- **📖 Story Sequence**: Generate consecutive images for visual storytelling or step-by-step processes
- **📊 Technical Diagrams**: Generate flowcharts, architecture diagrams, and technical illustrations
- **🔄 Automatic Fallback**: Automatically switch to a backup model if the primary model fails
- **⚡ Batch Generation**: Support parallel generation of multiple images
## 📋 Prerequisites
1. **Python 3.10+**
2. **API Key** — Choose one:
**A. Gemini Developer API** (AI Studio)
- `NANOBANANA_GEMINI_API_KEY` (recommended) / `NANOBANANA_GOOGLE_API_KEY`
- `GEMINI_API_KEY` / `GOOGLE_API_KEY` (backup)
- Obtain: <https://aistudio.google.com/apikey>
**B. Vertex AI Express Mode** (Google Cloud, available with newer models like `gemini-3.1-flash-image-preview`)
- `NANOBANANA_VERTEX_API_KEY` (recommended) / `VERTEX_API_KEY` (backup)
- Obtain: Google Cloud Console or AI Studio with GCP project binding
> Setting Vertex-specific variables automatically switches to Vertex; use `NANOBANANA_PROVIDER=vertex` (or `gemini`) to enforce.
## 🚀 Installation
### Using uvx (recommended)
```bash
uvx nanobanana-py
```
### Using pip
```bash
pip install nanobanana-py
```
### Using pipx
```bash
pipx install nanobanana-py
```
## ⚙️ Configuration
### Environment Variables
```bash
# API Key (required)
export NANOBANANA_GEMINI_API_KEY="your-api-key-here"
# Use a different model (default: gemini-2.5-flash-image)
export NANOBANANA_MODEL="gemini-3-pro-image-preview"
# Fallback models (comma-separated, tried in order if primary model fails)
export NANOBANANA_FALLBACK_MODELS="gemini-2.5-flash-image,gemini-2.0-flash-exp-image-generation"
# API timeout in seconds (default: 60)
export NANOBANANA_TIMEOUT="90"
# Custom output directory (default: current directory)
export NANOBANANA_OUTPUT_DIR="/path/to/output"
# Enable debug logging
export NANOBANANA_DEBUG="1"
```
### 🍌 Model Selection
This tool supports two models:
| Model | Description | Characteristics |
|------|-------------|---------------|
| `gemini-2.5-flash-image` | Default model | Fast, stable |
| `gemini-3-pro-image-preview` | Pro model | High-quality, supports 2K/4K |
### 🔄 Automatic Fallback Mechanism
When the primary model fails (timeout, overload, or error), it automatically switches to a backup model. The response includes fallback information:
```json
{
"success": true,
"message": "Successfully generated 1 image (using fallback model: gemini-2.5-flash-image, originally: gemini-3-pro-image-preview)",
"modelUsed": "gemini-2.5-flash-image",
"usedFallback": true,
"primaryModel": "gemini-3-pro-image-preview"
}
```
### Claude Code Integration
Add to `.mcp.json`:
```json
{
"mcpServers": {
"nanobanana": {
"command": "uvx",
"args": ["nanobanana-py"],
"env": {
"NANOBANANA_GEMINI_API_KEY": "your-api-key-here"
}
}
}
}
```
## 💡 Usage
### 🎨 generate_image - Generate Image
Generate a single or multiple images from text descriptions.
**Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | string | (required) | Image description |
| `files` | array | - | Reference image paths (1-13 images) |
| `filename` | string | - | Output file name |
| `output_count` | int | 1 | Number of images to generate (1-8) |
| `styles` | array | - | Art styles |
| `variations` | array | - | Variation types |
| `format` | string | "separate" | Output format (grid / separate) |
| `seed` | int | - | Random seed (for reproducibility) |
| `resolution` | string | "1K" | Resolution (1K / 2K / 4K) |
| `preview` | bool | false | Auto-preview |
| `no_preview` | bool | false | Force disable preview |
| `parallel` | int | 2 | Parallel generation count (1-8) |
**Available styles:**
- `photorealistic` - Photorealistic style
- `watercolor` - Watercolor style
- `oil-painting` - Oil painting technique
- `sketch` - Hand-drawn sketch style
- `pixel-art` - Retro pixel art style
- `anime` - Anime/manga style
- `vintage` - Retro/vintage aesthetic
- `modern` - Contemporary/modern style
- `abstract` - Abstract art style
- `minimalist` - Clean, minimalist design
**Available variations:**
- `lighting` - Different lighting conditions (dramatic, soft)
- `angle` - Different angles (bird's eye, close-up)
- `color-palette` - Different color palettes (warm, cool)
- `composition` - Different compositions (centered, rule of thirds)
- `mood` - Different moods/atmospheres (cheerful, dramatic)
- `season` - Different seasons (spring, winter)
- `time-of-day` - Different times of day (sunrise, sunset)
**Example:**
```python
# Single image
generate_image(prompt="A watercolor painting: a fox in a snowy forest")
# Multiple variations (with preview)
generate_image(prompt="A mountain landscape at sunset", output_count=3, preview=True)
# Specify output file name
generate_image(prompt="A mountain landscape at sunset", output_count=3, filename="sunset_mountains")
# Style variations
generate_image(
prompt="A landscape",
styles=["watercolor", "oil-painting"],
output_count=4
)
# Specify variations
generate_image(
prompt="A coffee shop interior",
variations=["lighting", "mood"],
preview=True
)
```
---
### ✏️ edit_image - Edit Image
Modify an existing image using natural language instructions.
**Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | string | (required) | Edit description |
| `file` | string | (required) | Input image path |
| `filename` | string | - | Output file name |
| `resolution` | string | "1K" | Resolution (1K / 2K / 4K) |
| `preview` | bool | false | Auto-preview |
| `no_preview` | bool | false | Force disable preview |
| `parallel` | int | 2 | Parallel generation count (1-8) |
**Example:**
```python
# Basic editing
edit_image(file="my_photo.png", prompt="Add sunglasses to the person")
# Specify output file name
edit_image(
file="my_photo.png",
prompt="Add sunglasses to the person",
filename="with_sunglasses"
)
# Edit and preview
edit_image(
file="portrait.jpg",
prompt="Change the background to a beach",
preview=True
)
```
---
### 🔧 restore_image - Restore Image
Restore and enhance old or damaged photos.
**Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | string | (required) | Restoration description |
| `file` | string | (required) | Input image path |
| `filename` | string | - | Output file name |
| `resolution` | string | "1K" | Resolution (1K / 2K / 4K) |
| `preview` | bool | false | Auto-preview |
| `no_preview` | bool | false | Force disable preview |
| `parallel` | int | 2 | Parallel generation count (1-8) |
**Example:**
```python
# Remove scratches
restore_image(
file="old_family_photo.jpg",
prompt="Remove scratches and enhance clarity"
)
# Enhance colors
restore_image(
file="damaged_photo.png",
prompt="Enhance colors and repair tears",
preview=True
)
```
---
### 🎯 generate_icon - Generate Icon
Generate multi-size app icons, favicons, and UI elements.
**Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | string | (required) | Icon description |
| `files` | array | - | Reference image paths (1-14 images) |
| `filename` | string | - | Output file name |
| `sizes` | array | [1024] | Sizes (16, 32, 64, 128, 256, 512, 1024) |
| `type` | string | "app-icon" | Type (app-icon / favicon / ui-element) |
| `style` | string | "modern" | Style (flat / skeuomorphic / minimal / modern) |
| `format` | string | "png" | Format (png / jpeg) |
| `background` | string | "transparent" | Background (transparent / white / black) |
| `corners` | string | "rounded" | Corners (rounded / sharp) |
| `resolution` | string | "1K" | Resolution (1K / 2K / 4K) |
| `preview` | bool | false | Auto-preview |
| `no_preview` | bool | false | Force disable preview |
| `parallel` | int | 2 | Parallel generation count (1-8) |
**Example:**
```python
# Multi-size app icon
generate_icon(
prompt="A coffee cup logo",
sizes=[64, 128, 256],
type="app-icon",
preview=True
)
# Favicon set
generate_icon(
prompt="Company logo",
type="favicon",
sizes=[16, 32, 64]
)
# UI element
generate_icon(
prompt="Settings gear icon",
type="ui-element",
style="minimal"
)
```
---
### 🎨 generate_pattern - Generate Pattern
Generate seamless patterns and background textures.
**Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | string | (required) | Pattern description |
| `files` | array | - | Reference image paths (1-14 images) |
| `filename` | string | - | Output file name |
| `size` | string | "256x256" | Size (128x128, 256x256, 512x512) |
| `type` | string | "seamless" | Type (seamless / texture / wallpaper) |
| `style` | string | "abstract" | Style (geometric / organic / abstract / floral / tech) |
| `density` | string | "medium" | Density (sparse / medium / dense) |
| `colors` | string | "colorful" | Colors (mono / duotone / colorful) |
| `repeat` | string | "tile" | Repeat mode (tile / mirror) |
| `resolution` | string | "1K" | Resolution (1K / 2K / 4K) |
| `preview` | bool | false | Auto-preview |
| `no_preview` | bool | false | Force disable preview |
| `parallel` | int | 2 | Parallel generation count (1-8) |
**Example:**
```python
# Seamless pattern
generate_pattern(
prompt="Geometric triangles",
type="seamless",
style="geometric",
preview=True
)
# Background texture
generate_pattern(
prompt="Wood texture",
type="texture",
colors="mono"
)
# Wallpaper pattern
generate_pattern(
prompt="Floral design",
type="wallpaper",
density="sparse"
)
```
---
### 📖 generate_story - Generate Story Sequence
Generate consecutive images for visual storytelling or step-by-step processes.
**Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | string | (required) | Story description |
| `files` | array | - | Reference image paths (1-14 images) |
| `filename` | string | - | Output file name |
| `steps` | int | 4 | Number of steps (2-8) |
| `type` | string | "story" | Type (story / process / tutorial / timeline) |
| `style` | string | "consistent" | Style consistency (consistent / evolving) |
| `layout` | string | "separate" | Layout (separate / grid / comic) |
| `transition` | string | "smooth" | Transition effect (smooth / dramatic / fade) |
| `format` | string | "individual" | Format (storyboard / individual) |
| `resolution` | string | "1K" | Resolution (1K / 2K / 4K) |
| `preview` | bool | false | Auto-preview |
| `no_preview` | bool | false | Force disable preview |
| `parallel` | int | 2 | Parallel generation count (1-8) |
**Example:**
```python
# Visual story sequence
generate_story(
prompt="A seed growing into a tree",
steps=4,
type="process",
preview=True
)
# Step-by-step tutorial
generate_story(
prompt="How to brew coffee",
steps=6,
type="tutorial"
)
# Timeline visualization
generate_story(
prompt="The evolution of smartphones",
steps=5,
type="timeline"
)
```
### 📊 generate_diagram - Generate Technical Diagrams
Generate professional technical diagrams, flowcharts, and architecture diagrams.
**Parameters:**
| Parameter | Type | Default | Description |
|------|------|--------|------|
| `prompt` | string | (required) | Diagram description |
| `files` | array | - | Reference image paths (1-14 images) |
| `filename` | string | - | Output file name |
| `type` | string | "flowchart" | Type (see below) |
| `style` | string | "professional" | Style (professional / clean / hand-drawn / technical) |
| `layout` | string | "hierarchical" | Layout (horizontal / vertical / hierarchical / circular) |
| `complexity` | string | "detailed" | Complexity (simple / detailed / comprehensive) |
| `colors` | string | "accent" | Color scheme (mono / accent / categorical) |
| `annotations` | string | "detailed" | Annotations (minimal / detailed) |
| `resolution` | string | "1K" | Resolution (1K / 2K / 4K) |
| `preview` | bool | false | Auto-preview |
| `no_preview` | bool | false | Force disable preview |
| `parallel` | int | 2 | Parallel generation count (1-8) |
**Diagram Types:**
| Type | Description |
|------|------|
| `flowchart` | Flowcharts, decision trees, workflows |
| `architecture` | System architecture, microservices, infrastructure |
| `network` | Network topology, server configuration |
| `database` | Database structure, entity relationships |
| `wireframe` | UI/UX wireframes, page layout |
| `mindmap` | Mind maps, concept hierarchy |
| `sequence` | Sequence diagrams, API interactions |
**Examples:**
```python
# System flowchart
generate_diagram(
prompt="User login flow",
type="flowchart",
style="professional",
preview=True
)
# System architecture diagram
generate_diagram(
prompt="Microservice architecture",
type="architecture",
complexity="detailed"
)
# Database structure
generate_diagram(
prompt="E-commerce database design",
type="database",
layout="hierarchical"
)
```
---
## 📁 File Management
### Smart File Name Generation
Images are saved with friendly file names based on the prompt:
- `"sunset over mountains"` → `sunset_over_mountains_20240101_123456_abc123.jpg`
- `"abstract art piece"` → `abstract_art_piece_20240101_123456_def456.jpg`
### Custom File Names
Use the `filename` parameter to specify the output file name:
- Single image: `filename="mountain_view"` → `mountain_view.jpg`
- Multiple images: `filename="mountain_view"` + `output_count=3` → `mountain_view_1.jpg`, `mountain_view_2.jpg`, `mountain_view_3.jpg`
### File Search Locations
When editing/repairing, search for input images in the following locations:
1. Current working directory
2. Output directory (`NANOBANANA_OUTPUT_DIR`)
3. User's home directory
### Output Directory
Generated images are saved to:
1. Directory specified by `NANOBANANA_OUTPUT_DIR` environment variable (if set)
2. `nanobanana-output/` subdirectory in the current working directory (default)
---
## 🛠️ Development
```bash
# Clone repository
git clone https://github.com/aspect-apps/nanobanana-py.git
cd nanobanana-py
# Install dependencies
uv sync
# Install development dependencies
uv sync --extra dev
# Run tests
uv run pytest
# Format code
uv run ruff format src/
uv run ruff check src/ --fix
```
---
## 🐛 Troubleshooting
### Common Issues
1. **"No API key found"**
Set the `NANOBANANA_GEMINI_API_KEY` environment variable:
```bash
export NANOBANANA_GEMINI_API_KEY="your-api-key-here"
```
2. **"Model timeout" or "Model overloaded"**
- Try again later, or
- Set `NANOBANANA_MODEL` to use a different model
- Automatic fallback mechanism will try to switch to a backup model
3. **"Image not found"**
Confirm that the input file is located in a supported search directory (see "File Search Locations")
4. **Images generated to incorrect directory**
Set the `NANOBANANA_OUTPUT_DIR` environment variable to specify the output directory:
```bash
export NANOBANANA_OUTPUT_DIR="/path/to/output"
```
### Debug Mode
Enable debug logging to diagnose issues:
```bash
export NANOBANANA_DEBUG="1"
```
---
## 📄 License
MIT
## 🤝 Acknowledgements
- Original [nanobanana](https://github.com/doggy8088/nanobanana) by Will
- Using [FastMCP](https://github.com/jlowin/fastmcp) framework
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available