Skip to main content
Glama

Gemini Flash Image MCP Server

by brunoqgalvao
README.md8.32 kB
# 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.

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/brunoqgalvao/gemini-image-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server