# Gemini Flash Image 2.5 Tool (Nano Banana)
A tool for generating and editing images using Google's Gemini 2.5 Flash Image API (affectionately known as "Nano Banana").
Includes both a **Python CLI tool** and a **Model Context Protocol (MCP) server** for integration with AI assistants like Claude Code.
## Features
- **Text-to-Image Generation**: Create images from text prompts
- **Image Editing**: Modify existing images with natural language instructions
- **Multi-Image Composition**: Combine multiple images into one
- **Flexible Aspect Ratios**: Support for 10 different aspect ratios
- **Character Consistency**: Maintain character appearance across multiple generations
- **MCP Server**: Integrate with Claude Code and other MCP clients
- **Command-Line Interface**: Easy-to-use CLI for quick operations
- **Python API**: Use as a library in your own projects
## Installation
### Option 1: MCP Server (Recommended for AI Assistants)
#### Simplest Install (using npx)
For Claude Code MCP configuration, you can reference the package directly via GitHub:
**Add to your MCP settings** (`~/.config/claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"gemini-image": {
"command": "npx",
"args": ["-y", "github:brunoqgalvao/gemini-image-mcp-server"],
"env": {
"GEMINI_API_KEY": "your_api_key_here"
}
}
}
}
```
Then restart Claude Code! The `generate_image` tool will be available instantly.
#### Local Install
```bash
# Clone the repository
git clone https://github.com/brunoqgalvao/gemini-image-mcp-server.git
cd gemini-image-mcp-server
# Run the installer
./install.sh
```
The installer will:
- Install Node.js dependencies
- Create a `.env` file from template
- Run validation tests
- Show you the MCP configuration to add to Claude Code
#### Manual Install
1. Clone or download this repository
2. Install Node.js dependencies:
```bash
npm install
```
3. Get your API key from [Google AI Studio](https://aistudio.google.com/apikey)
4. Create a `.env` file in the project directory:
```bash
GEMINI_API_KEY=your_api_key_here
```
5. Configure your MCP client (e.g., Claude Code):
**For macOS/Linux** - Add to `~/.config/claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"gemini-image": {
"command": "node",
"args": ["/absolute/path/to/agent-dispatcher/index.js"],
"env": {
"GEMINI_API_KEY": "your_api_key_here"
}
}
}
}
```
**For Windows** - Add to `%APPDATA%\Claude\claude_desktop_config.json`:
```json
{
"mcpServers": {
"gemini-image": {
"command": "node",
"args": ["C:\\absolute\\path\\to\\agent-dispatcher\\index.js"],
"env": {
"GEMINI_API_KEY": "your_api_key_here"
}
}
}
}
```
6. Restart Claude Code or your MCP client
#### Installing on Another Computer
**Easiest way** - Just use npx! On any computer with Node.js:
Add to Claude Code MCP settings:
```json
{
"mcpServers": {
"gemini-image": {
"command": "npx",
"args": ["-y", "github:brunoqgalvao/gemini-image-mcp-server"],
"env": {
"GEMINI_API_KEY": "your_api_key_here"
}
}
}
}
```
No cloning needed! `npx` will fetch and run it automatically.
**Alternative: Local installation**
```bash
# Clone and install
git clone https://github.com/brunoqgalvao/gemini-image-mcp-server.git
cd gemini-image-mcp-server
./install.sh
```
### Option 2: Python CLI Tool
1. Clone or download this repository
2. Install Python dependencies:
```bash
pip install -r requirements.txt
```
3. Get your API key from [Google AI Studio](https://aistudio.google.com/apikey)
4. Create a `.env` file in the project directory:
```bash
GEMINI_API_KEY=your_api_key_here
```
## Usage
### MCP Server
Once configured, the `generate_image` tool will be available in your MCP client:
**Parameters:**
- `prompt` (required): Text description of the image to generate or edits to make
- `output_path` (required): Path where the image will be saved (must end in .png)
- `input_images` (optional): Array of paths to input images for editing/composition
- `aspect_ratio` (optional): One of: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
- `image_only` (optional): Set to true for image-only output without text
**Example usage in Claude Code:**
```
"Generate a sunset over mountains and save it to sunset.png"
```
The MCP server will handle the API call and save the image automatically.
### Command Line
**Basic text-to-image generation:**
```bash
python gemini_image_tool.py "A cat eating a banana in space" -o cat_banana.png
```
**Edit an existing image:**
```bash
python gemini_image_tool.py "Remove the background" -i photo.jpg -o edited.png
```
**Compose multiple images:**
```bash
python gemini_image_tool.py "Combine these into a collage" -i img1.jpg -i img2.jpg -o collage.png
```
**Specify aspect ratio:**
```bash
python gemini_image_tool.py "A cinematic landscape" -o wide.png --aspect-ratio 21:9
```
**Image-only output (no text response):**
```bash
python gemini_image_tool.py "A red apple" -o apple.png --image-only
```
**Save full API response:**
```bash
python gemini_image_tool.py "A sunset" -o sunset.png --save-json response.json
```
### Python API
```python
from gemini_image_tool import GeminiImageTool
# Initialize the tool
tool = GeminiImageTool(api_key="your_api_key_here")
# Generate an image
result = tool.generate_content(
prompt="A futuristic city at night",
aspect_ratio="16:9",
output_path="city.png"
)
# Edit an image
result = tool.generate_content(
prompt="Make the sky purple",
input_images=["city.png"],
output_path="city_purple.png"
)
# Combine multiple images
result = tool.generate_content(
prompt="Create a before/after comparison",
input_images=["before.jpg", "after.jpg"],
aspect_ratio="2:1",
output_path="comparison.png"
)
```
## Available Aspect Ratios
- `1:1` - Square (default)
- `2:3` - Portrait
- `3:2` - Landscape
- `3:4` - Portrait
- `4:3` - Landscape
- `4:5` - Portrait
- `5:4` - Landscape
- `9:16` - Vertical (social media)
- `16:9` - Widescreen
- `21:9` - Cinematic
## Supported Image Formats
**Input:** JPG, JPEG, PNG, WebP, GIF
**Output:** PNG
## Pricing
As of 2025, Gemini 2.5 Flash Image is priced at:
- $30.00 per 1 million output tokens
- Each image = 1290 output tokens
- Cost per image: ~$0.039
## Use Cases
- **E-commerce**: Product photography and variations
- **Content Creation**: Social media graphics, blog images
- **Marketing**: Ad creatives, promotional materials
- **Storytelling**: Consistent character illustrations
- **Photo Editing**: Background removal, color correction, object removal
- **Design**: Logo variations, mockups, concept art
## Command-Line Arguments
```
positional arguments:
prompt Text prompt for image generation/editing
optional arguments:
-h, --help Show help message
-i INPUT, --input INPUT
Input image file path (can be specified multiple times)
-o OUTPUT, --output OUTPUT
Output image file path (default: output.png)
-a ASPECT_RATIO, --aspect-ratio ASPECT_RATIO
Output aspect ratio (default: 1:1)
--image-only Request image-only output (no text response)
--api-key API_KEY Google AI API key (or set GEMINI_API_KEY env variable)
--save-json SAVE_JSON
Save full API response to JSON file
```
## Error Handling
The tool includes comprehensive error handling for:
- Missing API keys
- Invalid image paths
- Unsupported image formats
- Invalid aspect ratios
- API request failures
- Network errors
## Notes
- All generated images include a SynthID watermark (added by Google)
- The model benefits from Gemini's world knowledge for enhanced generation
- Character consistency works best with clear, descriptive prompts
- For best results, be specific in your prompts
## Documentation
For more information about Gemini 2.5 Flash Image:
- [Official Documentation](https://ai.google.dev/gemini-api/docs/image-generation)
- [Google Developers Blog](https://developers.googleblog.com/en/introducing-gemini-2-5-flash-image/)
## License
This tool is provided as-is for use with the Gemini API. See Google's terms of service for API usage restrictions.
