# Ultimate Gemini MCP Server 🎨
> The most comprehensive MCP server for AI image generation, unifying Google's Gemini 2.5 Flash Image and Imagen 4/Ultra models with advanced features.
## ✨ Features
### Unified API Support
- **Gemini 2.5 Flash Image**: Advanced image generation with AI-powered prompt enhancement and editing
- **Imagen 4 & 4-Ultra**: High-quality image generation with professional controls
- Automatic model detection and parameter optimization
### Advanced Capabilities
- 🤖 **AI Prompt Enhancement**: Automatically optimize prompts using Gemini Flash for superior results
- 🎨 **Image Editing**: Modify existing images with natural language instructions
- 🚀 **Batch Processing**: Generate multiple images efficiently with parallel processing
- 🎯 **Character Consistency**: Maintain character features across multiple generations
- 🌍 **World Knowledge**: Integrate accurate real-world context for historical/factual subjects
- 🎭 **Multi-Image Blending**: Combine multiple visual elements naturally
- 🎲 **Reproducible Results**: Use seeds for consistent generation (Imagen)
- ⚫ **Negative Prompts**: Specify what to avoid in images (Imagen)
### Production Ready
- Comprehensive error handling and validation
- Configurable settings via environment variables
- Detailed logging and debugging
- MCP resources for configuration and model information
## 🎬 Showcase - See It In Action
> **Simple prompt → Mind-blowing results** - Watch AI prompt enhancement transform basic ideas into cinematic masterpieces.
### Example: Animal + Spider-Man Raimi Suit Blends
All images generated with **16:9 aspect ratio** and **AI prompt enhancement enabled**.
#### Original Prompt
```
a black shiba inu blended with spiderman raimi suit version
```
**Generated with Imagen 4**
- **Model**: `imagen-4`
- **Enhanced Prompt**: "A wide cinematic landscape composition capturing a hyper-detailed, photorealistic portrait of a Black Shiba Inu merged with the aesthetic of the Raimi Spider-Man suit. The dog's dense, black fur integrates seamlessly with the suit's signature sculpted, rubberized texture, featuring raised silver webbing across its body and limbs..."
- **Size**: 1.47 MB
- **Result**: Cinematic composition with dramatic chiaroscuro lighting
**Generated with Imagen 4 Ultra**
- **Model**: `imagen-4-ultra`
- **Enhanced Prompt**: "A hyper-detailed, photorealistic depiction of a black Shiba Inu fully integrated with the aesthetic and materials of the Tobey Maguire Raimi Spider-Man suit... dramatic, high-contrast Chiaroscuro lighting... heroic, mid-action leap across a rain-slicked urban rooftop..."
- **Size**: 1.59 MB
- **Result**: Ultra-high quality with enhanced material textures and volumetric fog
**Generated with Gemini 2.5 Flash (Nanobanana)**
- **Model**: `gemini-2.5-flash-image`
- **Enhanced Prompt**: "Cinematic wide landscape... formidable Black Shiba Inu hybrid... seamlessly merged with the iconic deep crimson and midnight black textures of the Raimi Spider-Man suit... dynamic, heroic three-quarter pose, mid-leap..."
- **Size**: 1.63 MB
- **Result**: Dynamic hero pose with intense atmospheric effects
---
#### Original Prompt
```
an american wirehair cat blended with spiderman raimi suit version
```
**Generated with Gemini 2.5 Flash (Nanobanana)**
- **Model**: `gemini-2.5-flash-image`
- **Enhanced Prompt**: "An imposing figure: an American Wirehair Cat hybrid, its naturally coarse, mottled fur seamlessly integrated with the iconic Sam Raimi Spider-Man suit... perched atop a rain-slicked, Gothic skyscraper gargoyle... high-contrast chiaroscuro, with powerful blue and red rim lighting..."
- **Size**: 1.62 MB
- **Result**: Gothic noir aesthetic with dramatic gargoyle perch
---
#### Original Prompt
```
a maine coon cat blended with spiderman raimi suit version
```
**Generated with Gemini 2.5 Flash (Nanobanana)**
- **Model**: `gemini-2.5-flash-image`
- **Enhanced Prompt**: "A hyper-detailed, photorealistic cinematic composition of a gigantic Maine Coon cat fused with the specific aesthetics of the Sam Raimi Spider-Man suit... dense fur coat mimics the suit's precise material textures... dramatic low-angle (worm's-eye view) to emphasize monumental scale..."
- **Size**: 1.61 MB
- **Result**: Emphasizes gigantic scale perfect for Maine Coon's natural size
---
### 🔥 Why These Results Are Incredible
1. **Simple Input → Professional Output**: Just a basic description produces cinematic, professionally-lit compositions
2. **Model Variety**: Compare Imagen 4, Imagen 4 Ultra, and Gemini 2.5 Flash results side-by-side
3. **AI Enhancement Magic**: See how prompt enhancement adds lighting, composition, and technical details
4. **Consistent Quality**: All images feature dramatic chiaroscuro lighting, atmospheric effects, and hyper-detailed textures
5. **Model-Specific Strengths**:
- Imagen 4 Ultra: Maximum quality and material detail
- Gemini 2.5 Flash: Dynamic poses and creative interpretations
- Imagen 4: Balanced speed and quality
## 🚀 Quick Start
### Prerequisites
- Python 3.11 or higher
- [Google Gemini API key](https://makersuite.google.com/app/apikey) (free)
### Installation
#### Option 1: Using uv (Recommended)
```bash
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install and run the server
uvx ultimate-gemini-mcp
```
#### Option 2: Using pip
```bash
pip install ultimate-gemini-mcp
```
#### Option 3: From Source
```bash
git clone <repository-url>
cd ultimate-gemini-mcp
uv sync
```
### Configuration
Create a `.env` file in your project directory:
```bash
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY
```
Or set environment variables directly:
```bash
export GEMINI_API_KEY=your_api_key_here
```
## 📖 Usage
### With Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"ultimate-gemini": {
"command": "uvx",
"args": ["ultimate-gemini-mcp"],
"env": {
"GEMINI_API_KEY": "your-api-key-here",
"OUTPUT_DIR": "/path/to/your/images"
}
}
}
}
```
**Important Notes:**
1. **OUTPUT_DIR is required** when using `uvx` to avoid read-only file system errors. Set it to an absolute path where you want generated images saved:
- **macOS**: `"/Users/yourusername/gemini_images"`
- **Windows**: `"C:\\Users\\YourUsername\\gemini_images"`
2. **uvx path issues on macOS**: If you get `spawn uvx ENOENT` errors, use the full path to uvx:
```json
"command": "/Users/yourusername/.local/bin/uvx"
```
**Config file locations:**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
### With Claude Code (VS Code)
```bash
# Add MCP server to Claude Code (with required OUTPUT_DIR)
claude mcp add ultimate-gemini \
--env GEMINI_API_KEY=your-api-key \
--env OUTPUT_DIR=/path/to/your/images \
-- uvx ultimate-gemini-mcp
```
**Note**: Replace `/path/to/your/images` with an absolute path to where you want images saved.
### With Cursor
Add to Cursor's MCP configuration (`.cursor/mcp.json`):
```json
{
"mcpServers": {
"ultimate-gemini": {
"command": "uvx",
"args": ["ultimate-gemini-mcp"],
"env": {
"GEMINI_API_KEY": "your-api-key-here",
"OUTPUT_DIR": "/path/to/your/images"
}
}
}
}
```
**Note**: Set `OUTPUT_DIR` to an absolute path where you want generated images saved.
## 🎯 Available Models
### Gemini Models
- **gemini-2.5-flash-image** (default): Advanced image generation with prompt enhancement and editing
### Imagen Models
- **imagen-4**: High-quality image generation with improved text rendering
- **imagen-4-fast**: Optimized for faster generation with good quality
- **imagen-4-ultra**: Highest quality with best prompt adherence and professional results
## 🛠️ Tools
### `generate_image`
Generate images using any supported model with comprehensive parameters.
**Parameters:**
- `prompt` (required): Text description of the image
- `model`: Model to use (default: gemini-2.5-flash-image)
- `enhance_prompt`: Automatically enhance prompt (default: true)
- `number_of_images`: Number of images to generate, 1-4 (default: 1)
- `aspect_ratio`: Aspect ratio like 1:1, 16:9, 9:16 (default: 1:1)
- `output_format`: Image format: png, jpeg, webp (default: png)
**Gemini-Specific Parameters:**
- `input_image_path`: Path to input image for editing
- `maintain_character_consistency`: Maintain character features across generations
- `blend_images`: Enable multi-image blending
- `use_world_knowledge`: Use real-world knowledge for context
**Imagen-Specific Parameters:**
- `person_generation`: Person policy: dont_allow, allow_adult, allow_all
- `negative_prompt`: What to avoid in the image
- `seed`: Random seed for reproducibility
**Example:**
```
Generate an image of "a serene mountain landscape at sunset with a lake reflection" using imagen-4-ultra
```
### `batch_generate`
Process multiple prompts efficiently with parallel batch processing.
**Parameters:**
- `prompts` (required): List of text prompts
- `model`: Model to use for all images
- `enhance_prompt`: Enhance all prompts (default: true)
- `aspect_ratio`: Aspect ratio for all images
- `batch_size`: Parallel processing size (default: from config)
**Example:**
```
Batch generate images for these prompts:
1. "minimalist logo design for a tech startup"
2. "modern dashboard UI design"
3. "mobile app wireframe"
```
## 🎨 Advanced Features
### AI Prompt Enhancement
When enabled (default), the server uses Gemini Flash to automatically enhance your prompts:
**Original:** `a cat wearing a space helmet`
**Enhanced:** `A photorealistic portrait of a domestic tabby cat wearing a futuristic space helmet, close-up composition, warm studio lighting, detailed fur texture, reflective helmet visor showing subtle reflections, soft focus background, professional photography style`
This significantly improves image quality without requiring you to be a prompt engineering expert!
### Image Editing
Use natural language to edit existing images (Gemini model):
```
Generate an image with:
- prompt: "Add a red scarf to the person"
- input_image_path: "/path/to/image.jpg"
```
### Character Consistency
Generate the same character in different scenes:
```
Generate an image of "a young wizard in a library, studying ancient books"
with maintain_character_consistency: true
```
Then:
```
Generate an image of "the same young wizard, now in a magical forest"
with maintain_character_consistency: true
```
### Reproducible Results
Use seeds for consistent generation (Imagen models):
```
Generate an image with:
- prompt: "a futuristic cityscape"
- model: "imagen-4-ultra"
- seed: 42
```
Running with the same seed will produce the same image.
## ⚙️ Configuration
### Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `GEMINI_API_KEY` | Google Gemini API key (required) | - |
| `OUTPUT_DIR` | Directory for generated images | `generated_images` |
| `ENABLE_PROMPT_ENHANCEMENT` | Enable AI prompt enhancement | `true` |
| `ENABLE_BATCH_PROCESSING` | Enable batch processing | `true` |
| `DEFAULT_GEMINI_MODEL` | Default Gemini model | `gemini-2.5-flash-image` |
| `DEFAULT_IMAGEN_MODEL` | Default Imagen model | `imagen-4-ultra` |
| `REQUEST_TIMEOUT` | API request timeout (seconds) | `60` |
| `MAX_BATCH_SIZE` | Maximum parallel batch size | `8` |
| `LOG_LEVEL` | Logging level | `INFO` |
## 📚 MCP Resources
### `models://list`
View all available models with descriptions and features.
### `settings://config`
View current server configuration.
## 🎭 Use Cases
### Web Development
- Hero images and banners
- UI/UX mockups and wireframes
- Logo and branding assets
- Placeholder images
### App Development
- App icons and splash screens
- User interface elements
- Marketing materials
- Documentation images
### Content Creation
- Blog post illustrations
- Social media graphics
- Presentation visuals
- Product mockups
### Creative Projects
- Character design iterations
- Concept art exploration
- Style variations
- Scene composition
## 📊 Comparison
| Feature | Gemini 2.5 Flash | Imagen 4/Fast/Ultra |
|---------|------------------|---------------------|
| Prompt Enhancement | ✅ Built-in | ✅ Built-in |
| Image Editing | ✅ Yes | ❌ No |
| Character Consistency | ✅ Yes | ❌ No |
| Multi-Image Blending | ✅ Yes | ❌ No |
| Negative Prompts | ❌ No | ✅ Yes |
| Seed-based Reproducibility | ❌ No | ✅ Yes |
| Person Generation Controls | ❌ No | ✅ Yes |
| Speed Options | Standard | Fast/Standard/Ultra |
| Best For | Editing, iteration, context-aware | Photorealism, final quality, speed |
## 🐛 Troubleshooting
### "spawn uvx ENOENT" error
- **Cause**: Claude Desktop cannot find the `uvx` command in its PATH
- **Solution**: Use the full path to uvx in your config:
```json
"command": "/Users/yourusername/.local/bin/uvx"
```
- Find your uvx location with: `which uvx`
### "[Errno 30] Read-only file system: 'generated_images'"
- **Cause**: When using `uvx`, the default directory is in a read-only cache location
- **Solution**: Add `OUTPUT_DIR` to your MCP config:
```json
"env": {
"GEMINI_API_KEY": "your-key",
"OUTPUT_DIR": "/Users/yourusername/gemini_images"
}
```
### "GEMINI_API_KEY not found"
- Add your API key to `.env` or environment variables
- Get a free key at [Google AI Studio](https://makersuite.google.com/app/apikey)
### "Content blocked by safety filters"
- Modify your prompt to comply with content policies
- Try rephrasing without potentially sensitive content
### "Rate limit exceeded"
- Wait a few moments and try again
- Consider upgrading your API plan for higher limits
### Images not saving
- Check that OUTPUT_DIR exists and is writable
- Verify you have sufficient disk space
- Create the directory manually: `mkdir -p /path/to/your/images`
## 🤝 Contributing
Contributions are welcome! This project combines the best features from multiple MCP servers:
- mcp-image (TypeScript): Prompt enhancement and editing features
- nanobanana-mcp-server (Python): Architecture and FastMCP integration
- gemini-imagen-mcp-server (TypeScript): Imagen API support and batch processing
## 📄 License
MIT License - see LICENSE file for details.
## 🙏 Acknowledgments
Built on the excellent work of:
- [mcp-image](https://github.com/shinpr/mcp-image) - Prompt enhancement concept
- [nanobanana-mcp-server](https://github.com/zhongweili/nanobanana-mcp-server) - FastMCP architecture
- [gemini-imagen-mcp-server](https://github.com/serkanhaslak/gemini-imagen-mcp-server) - Imagen integration
## 🔗 Links
- [Google AI Studio](https://makersuite.google.com/app/apikey) - Get your API key
- [Gemini API Documentation](https://ai.google.dev/gemini-api/docs)
- [Model Context Protocol](https://modelcontextprotocol.io/)
---
**Ready to create amazing AI-generated images?** Install now and start generating! 🚀
Raw data
{
"_id": null,
"home_page": null,
"name": "ultimate-gemini-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "ai, claude, fastmcp, gemini, google-ai, image-generation, imagen, mcp",
"author": null,
"author_email": "Ultimate Gemini MCP <noreply@example.com>",
"download_url": "https://files.pythonhosted.org/packages/f3/35/44b7920ddbeb3784e5dd64c9ebb3d851f4842f3c1ff223a394154dd87dce/ultimate_gemini_mcp-1.6.0.tar.gz",
"platform": null,
"description": "# Ultimate Gemini MCP Server \ud83c\udfa8\n\n> The most comprehensive MCP server for AI image generation, unifying Google's Gemini 2.5 Flash Image and Imagen 4/Ultra models with advanced features.\n\n## \u2728 Features\n\n### Unified API Support\n- **Gemini 2.5 Flash Image**: Advanced image generation with AI-powered prompt enhancement and editing\n- **Imagen 4 & 4-Ultra**: High-quality image generation with professional controls\n- Automatic model detection and parameter optimization\n\n### Advanced Capabilities\n- \ud83e\udd16 **AI Prompt Enhancement**: Automatically optimize prompts using Gemini Flash for superior results\n- \ud83c\udfa8 **Image Editing**: Modify existing images with natural language instructions\n- \ud83d\ude80 **Batch Processing**: Generate multiple images efficiently with parallel processing\n- \ud83c\udfaf **Character Consistency**: Maintain character features across multiple generations\n- \ud83c\udf0d **World Knowledge**: Integrate accurate real-world context for historical/factual subjects\n- \ud83c\udfad **Multi-Image Blending**: Combine multiple visual elements naturally\n- \ud83c\udfb2 **Reproducible Results**: Use seeds for consistent generation (Imagen)\n- \u26ab **Negative Prompts**: Specify what to avoid in images (Imagen)\n\n### Production Ready\n- Comprehensive error handling and validation\n- Configurable settings via environment variables\n- Detailed logging and debugging\n- MCP resources for configuration and model information\n\n## \ud83c\udfac Showcase - See It In Action\n\n> **Simple prompt \u2192 Mind-blowing results** - Watch AI prompt enhancement transform basic ideas into cinematic masterpieces.\n\n### Example: Animal + Spider-Man Raimi Suit Blends\n\nAll images generated with **16:9 aspect ratio** and **AI prompt enhancement enabled**.\n\n#### Original Prompt\n```\na black shiba inu blended with spiderman raimi suit version\n```\n\n**Generated with Imagen 4**\n\n\n\n- **Model**: `imagen-4`\n- **Enhanced Prompt**: \"A wide cinematic landscape composition capturing a hyper-detailed, photorealistic portrait of a Black Shiba Inu merged with the aesthetic of the Raimi Spider-Man suit. The dog's dense, black fur integrates seamlessly with the suit's signature sculpted, rubberized texture, featuring raised silver webbing across its body and limbs...\"\n- **Size**: 1.47 MB\n- **Result**: Cinematic composition with dramatic chiaroscuro lighting\n\n**Generated with Imagen 4 Ultra**\n\n\n\n- **Model**: `imagen-4-ultra`\n- **Enhanced Prompt**: \"A hyper-detailed, photorealistic depiction of a black Shiba Inu fully integrated with the aesthetic and materials of the Tobey Maguire Raimi Spider-Man suit... dramatic, high-contrast Chiaroscuro lighting... heroic, mid-action leap across a rain-slicked urban rooftop...\"\n- **Size**: 1.59 MB\n- **Result**: Ultra-high quality with enhanced material textures and volumetric fog\n\n**Generated with Gemini 2.5 Flash (Nanobanana)**\n\n\n\n- **Model**: `gemini-2.5-flash-image`\n- **Enhanced Prompt**: \"Cinematic wide landscape... formidable Black Shiba Inu hybrid... seamlessly merged with the iconic deep crimson and midnight black textures of the Raimi Spider-Man suit... dynamic, heroic three-quarter pose, mid-leap...\"\n- **Size**: 1.63 MB\n- **Result**: Dynamic hero pose with intense atmospheric effects\n\n---\n\n#### Original Prompt\n```\nan american wirehair cat blended with spiderman raimi suit version\n```\n\n**Generated with Gemini 2.5 Flash (Nanobanana)**\n\n\n\n- **Model**: `gemini-2.5-flash-image`\n- **Enhanced Prompt**: \"An imposing figure: an American Wirehair Cat hybrid, its naturally coarse, mottled fur seamlessly integrated with the iconic Sam Raimi Spider-Man suit... perched atop a rain-slicked, Gothic skyscraper gargoyle... high-contrast chiaroscuro, with powerful blue and red rim lighting...\"\n- **Size**: 1.62 MB\n- **Result**: Gothic noir aesthetic with dramatic gargoyle perch\n\n---\n\n#### Original Prompt\n```\na maine coon cat blended with spiderman raimi suit version\n```\n\n**Generated with Gemini 2.5 Flash (Nanobanana)**\n\n\n\n- **Model**: `gemini-2.5-flash-image`\n- **Enhanced Prompt**: \"A hyper-detailed, photorealistic cinematic composition of a gigantic Maine Coon cat fused with the specific aesthetics of the Sam Raimi Spider-Man suit... dense fur coat mimics the suit's precise material textures... dramatic low-angle (worm's-eye view) to emphasize monumental scale...\"\n- **Size**: 1.61 MB\n- **Result**: Emphasizes gigantic scale perfect for Maine Coon's natural size\n\n---\n\n### \ud83d\udd25 Why These Results Are Incredible\n\n1. **Simple Input \u2192 Professional Output**: Just a basic description produces cinematic, professionally-lit compositions\n2. **Model Variety**: Compare Imagen 4, Imagen 4 Ultra, and Gemini 2.5 Flash results side-by-side\n3. **AI Enhancement Magic**: See how prompt enhancement adds lighting, composition, and technical details\n4. **Consistent Quality**: All images feature dramatic chiaroscuro lighting, atmospheric effects, and hyper-detailed textures\n5. **Model-Specific Strengths**:\n - Imagen 4 Ultra: Maximum quality and material detail\n - Gemini 2.5 Flash: Dynamic poses and creative interpretations\n - Imagen 4: Balanced speed and quality\n\n## \ud83d\ude80 Quick Start\n\n### Prerequisites\n- Python 3.11 or higher\n- [Google Gemini API key](https://makersuite.google.com/app/apikey) (free)\n\n### Installation\n\n#### Option 1: Using uv (Recommended)\n```bash\n# Install uv if you haven't already\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install and run the server\nuvx ultimate-gemini-mcp\n```\n\n#### Option 2: Using pip\n```bash\npip install ultimate-gemini-mcp\n```\n\n#### Option 3: From Source\n```bash\ngit clone <repository-url>\ncd ultimate-gemini-mcp\nuv sync\n```\n\n### Configuration\n\nCreate a `.env` file in your project directory:\n```bash\ncp .env.example .env\n# Edit .env and add your GEMINI_API_KEY\n```\n\nOr set environment variables directly:\n```bash\nexport GEMINI_API_KEY=your_api_key_here\n```\n\n## \ud83d\udcd6 Usage\n\n### With Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"ultimate-gemini\": {\n \"command\": \"uvx\",\n \"args\": [\"ultimate-gemini-mcp\"],\n \"env\": {\n \"GEMINI_API_KEY\": \"your-api-key-here\",\n \"OUTPUT_DIR\": \"/path/to/your/images\"\n }\n }\n }\n}\n```\n\n**Important Notes:**\n\n1. **OUTPUT_DIR is required** when using `uvx` to avoid read-only file system errors. Set it to an absolute path where you want generated images saved:\n - **macOS**: `\"/Users/yourusername/gemini_images\"`\n - **Windows**: `\"C:\\\\Users\\\\YourUsername\\\\gemini_images\"`\n\n2. **uvx path issues on macOS**: If you get `spawn uvx ENOENT` errors, use the full path to uvx:\n ```json\n \"command\": \"/Users/yourusername/.local/bin/uvx\"\n ```\n\n**Config file locations:**\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n### With Claude Code (VS Code)\n\n```bash\n# Add MCP server to Claude Code (with required OUTPUT_DIR)\nclaude mcp add ultimate-gemini \\\n --env GEMINI_API_KEY=your-api-key \\\n --env OUTPUT_DIR=/path/to/your/images \\\n -- uvx ultimate-gemini-mcp\n```\n\n**Note**: Replace `/path/to/your/images` with an absolute path to where you want images saved.\n\n### With Cursor\n\nAdd to Cursor's MCP configuration (`.cursor/mcp.json`):\n\n```json\n{\n \"mcpServers\": {\n \"ultimate-gemini\": {\n \"command\": \"uvx\",\n \"args\": [\"ultimate-gemini-mcp\"],\n \"env\": {\n \"GEMINI_API_KEY\": \"your-api-key-here\",\n \"OUTPUT_DIR\": \"/path/to/your/images\"\n }\n }\n }\n}\n```\n\n**Note**: Set `OUTPUT_DIR` to an absolute path where you want generated images saved.\n\n## \ud83c\udfaf Available Models\n\n### Gemini Models\n- **gemini-2.5-flash-image** (default): Advanced image generation with prompt enhancement and editing\n\n### Imagen Models\n- **imagen-4**: High-quality image generation with improved text rendering\n- **imagen-4-fast**: Optimized for faster generation with good quality\n- **imagen-4-ultra**: Highest quality with best prompt adherence and professional results\n\n## \ud83d\udee0\ufe0f Tools\n\n### `generate_image`\n\nGenerate images using any supported model with comprehensive parameters.\n\n**Parameters:**\n- `prompt` (required): Text description of the image\n- `model`: Model to use (default: gemini-2.5-flash-image)\n- `enhance_prompt`: Automatically enhance prompt (default: true)\n- `number_of_images`: Number of images to generate, 1-4 (default: 1)\n- `aspect_ratio`: Aspect ratio like 1:1, 16:9, 9:16 (default: 1:1)\n- `output_format`: Image format: png, jpeg, webp (default: png)\n\n**Gemini-Specific Parameters:**\n- `input_image_path`: Path to input image for editing\n- `maintain_character_consistency`: Maintain character features across generations\n- `blend_images`: Enable multi-image blending\n- `use_world_knowledge`: Use real-world knowledge for context\n\n**Imagen-Specific Parameters:**\n- `person_generation`: Person policy: dont_allow, allow_adult, allow_all\n- `negative_prompt`: What to avoid in the image\n- `seed`: Random seed for reproducibility\n\n**Example:**\n```\nGenerate an image of \"a serene mountain landscape at sunset with a lake reflection\" using imagen-4-ultra\n```\n\n### `batch_generate`\n\nProcess multiple prompts efficiently with parallel batch processing.\n\n**Parameters:**\n- `prompts` (required): List of text prompts\n- `model`: Model to use for all images\n- `enhance_prompt`: Enhance all prompts (default: true)\n- `aspect_ratio`: Aspect ratio for all images\n- `batch_size`: Parallel processing size (default: from config)\n\n**Example:**\n```\nBatch generate images for these prompts:\n1. \"minimalist logo design for a tech startup\"\n2. \"modern dashboard UI design\"\n3. \"mobile app wireframe\"\n```\n\n## \ud83c\udfa8 Advanced Features\n\n### AI Prompt Enhancement\n\nWhen enabled (default), the server uses Gemini Flash to automatically enhance your prompts:\n\n**Original:** `a cat wearing a space helmet`\n\n**Enhanced:** `A photorealistic portrait of a domestic tabby cat wearing a futuristic space helmet, close-up composition, warm studio lighting, detailed fur texture, reflective helmet visor showing subtle reflections, soft focus background, professional photography style`\n\nThis significantly improves image quality without requiring you to be a prompt engineering expert!\n\n### Image Editing\n\nUse natural language to edit existing images (Gemini model):\n\n```\nGenerate an image with:\n- prompt: \"Add a red scarf to the person\"\n- input_image_path: \"/path/to/image.jpg\"\n```\n\n### Character Consistency\n\nGenerate the same character in different scenes:\n\n```\nGenerate an image of \"a young wizard in a library, studying ancient books\"\nwith maintain_character_consistency: true\n```\n\nThen:\n```\nGenerate an image of \"the same young wizard, now in a magical forest\"\nwith maintain_character_consistency: true\n```\n\n### Reproducible Results\n\nUse seeds for consistent generation (Imagen models):\n\n```\nGenerate an image with:\n- prompt: \"a futuristic cityscape\"\n- model: \"imagen-4-ultra\"\n- seed: 42\n```\n\nRunning with the same seed will produce the same image.\n\n## \u2699\ufe0f Configuration\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `GEMINI_API_KEY` | Google Gemini API key (required) | - |\n| `OUTPUT_DIR` | Directory for generated images | `generated_images` |\n| `ENABLE_PROMPT_ENHANCEMENT` | Enable AI prompt enhancement | `true` |\n| `ENABLE_BATCH_PROCESSING` | Enable batch processing | `true` |\n| `DEFAULT_GEMINI_MODEL` | Default Gemini model | `gemini-2.5-flash-image` |\n| `DEFAULT_IMAGEN_MODEL` | Default Imagen model | `imagen-4-ultra` |\n| `REQUEST_TIMEOUT` | API request timeout (seconds) | `60` |\n| `MAX_BATCH_SIZE` | Maximum parallel batch size | `8` |\n| `LOG_LEVEL` | Logging level | `INFO` |\n\n## \ud83d\udcda MCP Resources\n\n### `models://list`\nView all available models with descriptions and features.\n\n### `settings://config`\nView current server configuration.\n\n## \ud83c\udfad Use Cases\n\n### Web Development\n- Hero images and banners\n- UI/UX mockups and wireframes\n- Logo and branding assets\n- Placeholder images\n\n### App Development\n- App icons and splash screens\n- User interface elements\n- Marketing materials\n- Documentation images\n\n### Content Creation\n- Blog post illustrations\n- Social media graphics\n- Presentation visuals\n- Product mockups\n\n### Creative Projects\n- Character design iterations\n- Concept art exploration\n- Style variations\n- Scene composition\n\n## \ud83d\udcca Comparison\n\n| Feature | Gemini 2.5 Flash | Imagen 4/Fast/Ultra |\n|---------|------------------|---------------------|\n| Prompt Enhancement | \u2705 Built-in | \u2705 Built-in |\n| Image Editing | \u2705 Yes | \u274c No |\n| Character Consistency | \u2705 Yes | \u274c No |\n| Multi-Image Blending | \u2705 Yes | \u274c No |\n| Negative Prompts | \u274c No | \u2705 Yes |\n| Seed-based Reproducibility | \u274c No | \u2705 Yes |\n| Person Generation Controls | \u274c No | \u2705 Yes |\n| Speed Options | Standard | Fast/Standard/Ultra |\n| Best For | Editing, iteration, context-aware | Photorealism, final quality, speed |\n\n## \ud83d\udc1b Troubleshooting\n\n### \"spawn uvx ENOENT\" error\n- **Cause**: Claude Desktop cannot find the `uvx` command in its PATH\n- **Solution**: Use the full path to uvx in your config:\n ```json\n \"command\": \"/Users/yourusername/.local/bin/uvx\"\n ```\n- Find your uvx location with: `which uvx`\n\n### \"[Errno 30] Read-only file system: 'generated_images'\"\n- **Cause**: When using `uvx`, the default directory is in a read-only cache location\n- **Solution**: Add `OUTPUT_DIR` to your MCP config:\n ```json\n \"env\": {\n \"GEMINI_API_KEY\": \"your-key\",\n \"OUTPUT_DIR\": \"/Users/yourusername/gemini_images\"\n }\n ```\n\n### \"GEMINI_API_KEY not found\"\n- Add your API key to `.env` or environment variables\n- Get a free key at [Google AI Studio](https://makersuite.google.com/app/apikey)\n\n### \"Content blocked by safety filters\"\n- Modify your prompt to comply with content policies\n- Try rephrasing without potentially sensitive content\n\n### \"Rate limit exceeded\"\n- Wait a few moments and try again\n- Consider upgrading your API plan for higher limits\n\n### Images not saving\n- Check that OUTPUT_DIR exists and is writable\n- Verify you have sufficient disk space\n- Create the directory manually: `mkdir -p /path/to/your/images`\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! This project combines the best features from multiple MCP servers:\n- mcp-image (TypeScript): Prompt enhancement and editing features\n- nanobanana-mcp-server (Python): Architecture and FastMCP integration\n- gemini-imagen-mcp-server (TypeScript): Imagen API support and batch processing\n\n## \ud83d\udcc4 License\n\nMIT License - see LICENSE file for details.\n\n## \ud83d\ude4f Acknowledgments\n\nBuilt on the excellent work of:\n- [mcp-image](https://github.com/shinpr/mcp-image) - Prompt enhancement concept\n- [nanobanana-mcp-server](https://github.com/zhongweili/nanobanana-mcp-server) - FastMCP architecture\n- [gemini-imagen-mcp-server](https://github.com/serkanhaslak/gemini-imagen-mcp-server) - Imagen integration\n\n## \ud83d\udd17 Links\n\n- [Google AI Studio](https://makersuite.google.com/app/apikey) - Get your API key\n- [Gemini API Documentation](https://ai.google.dev/gemini-api/docs)\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n\n---\n\n**Ready to create amazing AI-generated images?** Install now and start generating! \ud83d\ude80\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Ultimate image generation MCP server unifying Gemini 2.5 Flash Image and Imagen 4/Fast/Ultra with advanced features",
"version": "1.6.0",
"project_urls": {
"Documentation": "https://github.com/anand-92/ultimate-image-gen-mcp/blob/main/README.md",
"Homepage": "https://github.com/anand-92/ultimate-image-gen-mcp",
"Issues": "https://github.com/anand-92/ultimate-image-gen-mcp/issues",
"Repository": "https://github.com/anand-92/ultimate-image-gen-mcp"
},
"split_keywords": [
"ai",
" claude",
" fastmcp",
" gemini",
" google-ai",
" image-generation",
" imagen",
" mcp"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7568854e365760177b9e95219c002970548c31a866a709352fa89013410ad20b",
"md5": "44e0872c181cd1fb1e5f56b4af47d595",
"sha256": "e6ef3fa7dadb337e3a749ae31d2b0911e3912f19dac7c8c9d144db02cdb7f23e"
},
"downloads": -1,
"filename": "ultimate_gemini_mcp-1.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "44e0872c181cd1fb1e5f56b4af47d595",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 30870,
"upload_time": "2025-10-26T07:14:03",
"upload_time_iso_8601": "2025-10-26T07:14:03.813137Z",
"url": "https://files.pythonhosted.org/packages/75/68/854e365760177b9e95219c002970548c31a866a709352fa89013410ad20b/ultimate_gemini_mcp-1.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f33544b7920ddbeb3784e5dd64c9ebb3d851f4842f3c1ff223a394154dd87dce",
"md5": "5208e1185d544a80cd6a89f8797039eb",
"sha256": "49ca119df682bf3c381c30551c23e3cb8640517a69a1a7fe162a0949cbffbce3"
},
"downloads": -1,
"filename": "ultimate_gemini_mcp-1.6.0.tar.gz",
"has_sig": false,
"md5_digest": "5208e1185d544a80cd6a89f8797039eb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 37335,
"upload_time": "2025-10-26T07:14:05",
"upload_time_iso_8601": "2025-10-26T07:14:05.004838Z",
"url": "https://files.pythonhosted.org/packages/f3/35/44b7920ddbeb3784e5dd64c9ebb3d851f4842f3c1ff223a394154dd87dce/ultimate_gemini_mcp-1.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-26 07:14:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "anand-92",
"github_project": "ultimate-image-gen-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ultimate-gemini-mcp"
}
JSON
