Gemini Flash Image MCP Server

# 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.