ultimate-gemini-mcp 1.0.1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Potentially problematic release.
This version of ultimate-gemini-mcp might be problematic. Click here for more details.
- src/__init__.py +16 -0
- src/config/__init__.py +32 -0
- src/config/constants.py +77 -0
- src/config/settings.py +143 -0
- src/core/__init__.py +55 -0
- src/core/exceptions.py +60 -0
- src/core/validation.py +161 -0
- src/server.py +166 -0
- src/services/__init__.py +15 -0
- src/services/gemini_client.py +230 -0
- src/services/image_service.py +243 -0
- src/services/imagen_client.py +175 -0
- src/services/prompt_enhancer.py +140 -0
- src/tools/__init__.py +11 -0
- src/tools/batch_generate.py +159 -0
- src/tools/generate_image.py +252 -0
- ultimate_gemini_mcp-1.0.1.dist-info/METADATA +372 -0
- ultimate_gemini_mcp-1.0.1.dist-info/RECORD +21 -0
- ultimate_gemini_mcp-1.0.1.dist-info/WHEEL +4 -0
- ultimate_gemini_mcp-1.0.1.dist-info/entry_points.txt +2 -0
- ultimate_gemini_mcp-1.0.1.dist-info/licenses/LICENSE +31 -0
|
@@ -0,0 +1,252 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Image generation tool supporting both Gemini and Imagen models.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
import base64
|
|
6
|
+
import logging
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
from typing import Any
|
|
9
|
+
|
|
10
|
+
from fastmcp import Image
|
|
11
|
+
|
|
12
|
+
from ..config import ALL_MODELS, ASPECT_RATIOS, get_settings
|
|
13
|
+
from ..core import (
|
|
14
|
+
validate_aspect_ratio,
|
|
15
|
+
validate_image_format,
|
|
16
|
+
validate_model,
|
|
17
|
+
validate_number_of_images,
|
|
18
|
+
validate_person_generation,
|
|
19
|
+
validate_prompt,
|
|
20
|
+
validate_seed,
|
|
21
|
+
)
|
|
22
|
+
from ..services import ImageService
|
|
23
|
+
|
|
24
|
+
logger = logging.getLogger(__name__)
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
async def generate_image_tool(
|
|
28
|
+
prompt: str,
|
|
29
|
+
model: str | None = None,
|
|
30
|
+
enhance_prompt: bool = True,
|
|
31
|
+
number_of_images: int = 1,
|
|
32
|
+
aspect_ratio: str = "1:1",
|
|
33
|
+
output_format: str = "png",
|
|
34
|
+
# Gemini-specific options
|
|
35
|
+
input_image_path: str | None = None,
|
|
36
|
+
maintain_character_consistency: bool = False,
|
|
37
|
+
blend_images: bool = False,
|
|
38
|
+
use_world_knowledge: bool = False,
|
|
39
|
+
# Imagen-specific options
|
|
40
|
+
person_generation: str = "allow_adult",
|
|
41
|
+
negative_prompt: str | None = None,
|
|
42
|
+
seed: int | None = None,
|
|
43
|
+
# Output options
|
|
44
|
+
save_to_disk: bool = True,
|
|
45
|
+
**kwargs: Any,
|
|
46
|
+
) -> dict[str, Any]:
|
|
47
|
+
"""
|
|
48
|
+
Generate images using Gemini or Imagen models.
|
|
49
|
+
|
|
50
|
+
Args:
|
|
51
|
+
prompt: Text description for image generation
|
|
52
|
+
model: Model to use (gemini-2.5-flash-image, imagen-3, imagen-4, imagen-4-ultra)
|
|
53
|
+
enhance_prompt: Automatically enhance prompt for better results
|
|
54
|
+
number_of_images: Number of images to generate (1-4)
|
|
55
|
+
aspect_ratio: Image aspect ratio (1:1, 16:9, 9:16, etc.)
|
|
56
|
+
output_format: Image format (png, jpeg, webp)
|
|
57
|
+
input_image_path: Path to input image for editing (Gemini only)
|
|
58
|
+
maintain_character_consistency: Maintain character features across generations (Gemini)
|
|
59
|
+
blend_images: Enable multi-image blending (Gemini)
|
|
60
|
+
use_world_knowledge: Use real-world knowledge for context (Gemini)
|
|
61
|
+
person_generation: Person generation policy (Imagen: dont_allow, allow_adult, allow_all)
|
|
62
|
+
negative_prompt: What to avoid in the image (Imagen)
|
|
63
|
+
seed: Random seed for reproducibility (Imagen)
|
|
64
|
+
save_to_disk: Save images to output directory
|
|
65
|
+
|
|
66
|
+
Returns:
|
|
67
|
+
Dict with generated images and metadata
|
|
68
|
+
"""
|
|
69
|
+
# Validate inputs
|
|
70
|
+
validate_prompt(prompt)
|
|
71
|
+
if model:
|
|
72
|
+
validate_model(model)
|
|
73
|
+
validate_number_of_images(number_of_images)
|
|
74
|
+
validate_aspect_ratio(aspect_ratio)
|
|
75
|
+
validate_image_format(output_format)
|
|
76
|
+
|
|
77
|
+
if person_generation:
|
|
78
|
+
validate_person_generation(person_generation)
|
|
79
|
+
if seed is not None:
|
|
80
|
+
validate_seed(seed)
|
|
81
|
+
|
|
82
|
+
# Get settings
|
|
83
|
+
settings = get_settings()
|
|
84
|
+
|
|
85
|
+
# Determine model
|
|
86
|
+
if model is None:
|
|
87
|
+
model = settings.api.default_gemini_model
|
|
88
|
+
|
|
89
|
+
# Initialize image service
|
|
90
|
+
image_service = ImageService(
|
|
91
|
+
api_key=settings.api.gemini_api_key,
|
|
92
|
+
enable_enhancement=settings.api.enable_prompt_enhancement,
|
|
93
|
+
timeout=settings.api.request_timeout,
|
|
94
|
+
)
|
|
95
|
+
|
|
96
|
+
try:
|
|
97
|
+
# Prepare parameters based on model type
|
|
98
|
+
params: dict[str, Any] = {
|
|
99
|
+
"aspect_ratio": aspect_ratio,
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
# Add input image if provided (Gemini)
|
|
103
|
+
if input_image_path:
|
|
104
|
+
image_path = Path(input_image_path)
|
|
105
|
+
if image_path.exists():
|
|
106
|
+
image_data = base64.b64encode(image_path.read_bytes()).decode()
|
|
107
|
+
params["input_image"] = image_data
|
|
108
|
+
else:
|
|
109
|
+
logger.warning(f"Input image not found: {input_image_path}")
|
|
110
|
+
|
|
111
|
+
# Add Gemini-specific options
|
|
112
|
+
if maintain_character_consistency:
|
|
113
|
+
params["maintainCharacterConsistency"] = True
|
|
114
|
+
if blend_images:
|
|
115
|
+
params["blendImages"] = True
|
|
116
|
+
if use_world_knowledge:
|
|
117
|
+
params["useWorldKnowledge"] = True
|
|
118
|
+
|
|
119
|
+
# Add Imagen-specific options
|
|
120
|
+
if model.startswith("imagen"):
|
|
121
|
+
params["number_of_images"] = number_of_images
|
|
122
|
+
params["output_format"] = f"image/{output_format}"
|
|
123
|
+
params["person_generation"] = person_generation
|
|
124
|
+
if negative_prompt:
|
|
125
|
+
params["negative_prompt"] = negative_prompt
|
|
126
|
+
if seed is not None:
|
|
127
|
+
params["seed"] = seed
|
|
128
|
+
|
|
129
|
+
# Generate images
|
|
130
|
+
results = await image_service.generate(
|
|
131
|
+
prompt=prompt,
|
|
132
|
+
model=model,
|
|
133
|
+
enhance_prompt=enhance_prompt and settings.api.enable_prompt_enhancement,
|
|
134
|
+
**params
|
|
135
|
+
)
|
|
136
|
+
|
|
137
|
+
# Prepare response
|
|
138
|
+
response = {
|
|
139
|
+
"success": True,
|
|
140
|
+
"model": model,
|
|
141
|
+
"prompt": prompt,
|
|
142
|
+
"images_generated": len(results),
|
|
143
|
+
"images": [],
|
|
144
|
+
"metadata": {
|
|
145
|
+
"enhance_prompt": enhance_prompt,
|
|
146
|
+
"aspect_ratio": aspect_ratio,
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
# Save images and prepare for MCP response
|
|
151
|
+
for result in results:
|
|
152
|
+
image_info = {
|
|
153
|
+
"index": result.index,
|
|
154
|
+
"size": result.get_size(),
|
|
155
|
+
"timestamp": result.timestamp.isoformat(),
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
if save_to_disk:
|
|
159
|
+
# Save to output directory
|
|
160
|
+
file_path = result.save(settings.output_dir)
|
|
161
|
+
image_info["path"] = str(file_path)
|
|
162
|
+
image_info["filename"] = file_path.name
|
|
163
|
+
|
|
164
|
+
# Add enhanced prompt info
|
|
165
|
+
if "enhanced_prompt" in result.metadata:
|
|
166
|
+
image_info["enhanced_prompt"] = result.metadata["enhanced_prompt"]
|
|
167
|
+
|
|
168
|
+
response["images"].append(image_info)
|
|
169
|
+
|
|
170
|
+
return response
|
|
171
|
+
|
|
172
|
+
finally:
|
|
173
|
+
await image_service.close()
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
def register_generate_image_tool(mcp_server: Any) -> None:
|
|
177
|
+
"""Register generate_image tool with MCP server."""
|
|
178
|
+
|
|
179
|
+
@mcp_server.tool()
|
|
180
|
+
async def generate_image(
|
|
181
|
+
prompt: str,
|
|
182
|
+
model: str | None = None,
|
|
183
|
+
enhance_prompt: bool = True,
|
|
184
|
+
number_of_images: int = 1,
|
|
185
|
+
aspect_ratio: str = "1:1",
|
|
186
|
+
output_format: str = "png",
|
|
187
|
+
input_image_path: str | None = None,
|
|
188
|
+
maintain_character_consistency: bool = False,
|
|
189
|
+
blend_images: bool = False,
|
|
190
|
+
use_world_knowledge: bool = False,
|
|
191
|
+
person_generation: str = "allow_adult",
|
|
192
|
+
negative_prompt: str | None = None,
|
|
193
|
+
seed: int | None = None,
|
|
194
|
+
) -> str:
|
|
195
|
+
"""
|
|
196
|
+
Generate images using Google's Gemini or Imagen models.
|
|
197
|
+
|
|
198
|
+
Supports both:
|
|
199
|
+
- Gemini 2.5 Flash Image: Advanced image generation with editing, prompt enhancement
|
|
200
|
+
- Imagen 4/Ultra: High-quality image generation with advanced controls
|
|
201
|
+
|
|
202
|
+
Args:
|
|
203
|
+
prompt: Text description of the image to generate
|
|
204
|
+
model: Model to use (default: gemini-2.5-flash-image)
|
|
205
|
+
enhance_prompt: Automatically enhance prompt using AI (default: True)
|
|
206
|
+
number_of_images: Number of images to generate, 1-4 (default: 1)
|
|
207
|
+
aspect_ratio: Image aspect ratio like 1:1, 16:9, 9:16 (default: 1:1)
|
|
208
|
+
output_format: Image format: png, jpeg, webp (default: png)
|
|
209
|
+
input_image_path: Path to input image for editing (Gemini only)
|
|
210
|
+
maintain_character_consistency: Maintain character features (Gemini only)
|
|
211
|
+
blend_images: Enable multi-image blending (Gemini only)
|
|
212
|
+
use_world_knowledge: Use real-world knowledge (Gemini only)
|
|
213
|
+
person_generation: Person policy: dont_allow, allow_adult, allow_all (Imagen only)
|
|
214
|
+
negative_prompt: What to avoid in the image (Imagen only)
|
|
215
|
+
seed: Random seed for reproducibility (Imagen only)
|
|
216
|
+
|
|
217
|
+
Available models:
|
|
218
|
+
- gemini-2.5-flash-image (default)
|
|
219
|
+
- imagen-4
|
|
220
|
+
- imagen-4-fast
|
|
221
|
+
- imagen-4-ultra
|
|
222
|
+
|
|
223
|
+
Returns:
|
|
224
|
+
JSON string with generation results and file paths
|
|
225
|
+
"""
|
|
226
|
+
try:
|
|
227
|
+
result = await generate_image_tool(
|
|
228
|
+
prompt=prompt,
|
|
229
|
+
model=model,
|
|
230
|
+
enhance_prompt=enhance_prompt,
|
|
231
|
+
number_of_images=number_of_images,
|
|
232
|
+
aspect_ratio=aspect_ratio,
|
|
233
|
+
output_format=output_format,
|
|
234
|
+
input_image_path=input_image_path,
|
|
235
|
+
maintain_character_consistency=maintain_character_consistency,
|
|
236
|
+
blend_images=blend_images,
|
|
237
|
+
use_world_knowledge=use_world_knowledge,
|
|
238
|
+
person_generation=person_generation,
|
|
239
|
+
negative_prompt=negative_prompt,
|
|
240
|
+
seed=seed,
|
|
241
|
+
)
|
|
242
|
+
|
|
243
|
+
import json
|
|
244
|
+
return json.dumps(result, indent=2)
|
|
245
|
+
|
|
246
|
+
except Exception as e:
|
|
247
|
+
logger.error(f"Error generating image: {e}")
|
|
248
|
+
return json.dumps({
|
|
249
|
+
"success": False,
|
|
250
|
+
"error": str(e),
|
|
251
|
+
"error_type": type(e).__name__
|
|
252
|
+
}, indent=2)
|
|
@@ -0,0 +1,372 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: ultimate-gemini-mcp
|
|
3
|
+
Version: 1.0.1
|
|
4
|
+
Summary: Ultimate image generation MCP server unifying Gemini 2.5 Flash Image and Imagen 4/Fast/Ultra with advanced features
|
|
5
|
+
Project-URL: Homepage, https://github.com/anand-92/ultimate-image-gen-mcp
|
|
6
|
+
Project-URL: Repository, https://github.com/anand-92/ultimate-image-gen-mcp
|
|
7
|
+
Project-URL: Issues, https://github.com/anand-92/ultimate-image-gen-mcp/issues
|
|
8
|
+
Project-URL: Documentation, https://github.com/anand-92/ultimate-image-gen-mcp/blob/main/README.md
|
|
9
|
+
Author-email: Ultimate Gemini MCP <noreply@example.com>
|
|
10
|
+
License: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: ai,claude,fastmcp,gemini,google-ai,image-generation,imagen,mcp
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
20
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
21
|
+
Requires-Python: >=3.11
|
|
22
|
+
Requires-Dist: aiohttp>=3.9.0
|
|
23
|
+
Requires-Dist: fastmcp>=2.11.0
|
|
24
|
+
Requires-Dist: google-genai>=0.3.0
|
|
25
|
+
Requires-Dist: httpx>=0.27.0
|
|
26
|
+
Requires-Dist: pillow>=10.4.0
|
|
27
|
+
Requires-Dist: pydantic-settings>=2.0.0
|
|
28
|
+
Requires-Dist: pydantic>=2.0.0
|
|
29
|
+
Provides-Extra: dev
|
|
30
|
+
Requires-Dist: mypy>=1.8.0; extra == 'dev'
|
|
31
|
+
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
|
|
32
|
+
Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
|
|
33
|
+
Requires-Dist: pytest>=8.0.0; extra == 'dev'
|
|
34
|
+
Requires-Dist: ruff>=0.8.0; extra == 'dev'
|
|
35
|
+
Description-Content-Type: text/markdown
|
|
36
|
+
|
|
37
|
+
# Ultimate Gemini MCP Server 🎨
|
|
38
|
+
|
|
39
|
+
> 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.
|
|
40
|
+
|
|
41
|
+
## ✨ Features
|
|
42
|
+
|
|
43
|
+
### Unified API Support
|
|
44
|
+
- **Gemini 2.5 Flash Image**: Advanced image generation with AI-powered prompt enhancement and editing
|
|
45
|
+
- **Imagen 4 & 4-Ultra**: High-quality image generation with professional controls
|
|
46
|
+
- Automatic model detection and parameter optimization
|
|
47
|
+
|
|
48
|
+
### Advanced Capabilities
|
|
49
|
+
- 🤖 **AI Prompt Enhancement**: Automatically optimize prompts using Gemini Flash for superior results
|
|
50
|
+
- 🎨 **Image Editing**: Modify existing images with natural language instructions
|
|
51
|
+
- 🚀 **Batch Processing**: Generate multiple images efficiently with parallel processing
|
|
52
|
+
- 🎯 **Character Consistency**: Maintain character features across multiple generations
|
|
53
|
+
- 🌍 **World Knowledge**: Integrate accurate real-world context for historical/factual subjects
|
|
54
|
+
- 🎭 **Multi-Image Blending**: Combine multiple visual elements naturally
|
|
55
|
+
- 🎲 **Reproducible Results**: Use seeds for consistent generation (Imagen)
|
|
56
|
+
- ⚫ **Negative Prompts**: Specify what to avoid in images (Imagen)
|
|
57
|
+
|
|
58
|
+
### Production Ready
|
|
59
|
+
- Comprehensive error handling and validation
|
|
60
|
+
- Configurable settings via environment variables
|
|
61
|
+
- Detailed logging and debugging
|
|
62
|
+
- MCP resources for configuration and model information
|
|
63
|
+
|
|
64
|
+
## 🚀 Quick Start
|
|
65
|
+
|
|
66
|
+
### Prerequisites
|
|
67
|
+
- Python 3.11 or higher
|
|
68
|
+
- [Google Gemini API key](https://makersuite.google.com/app/apikey) (free)
|
|
69
|
+
|
|
70
|
+
### Installation
|
|
71
|
+
|
|
72
|
+
#### Option 1: Using uv (Recommended)
|
|
73
|
+
```bash
|
|
74
|
+
# Install uv if you haven't already
|
|
75
|
+
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
76
|
+
|
|
77
|
+
# Install and run the server
|
|
78
|
+
uvx ultimate-gemini-mcp
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
#### Option 2: Using pip
|
|
82
|
+
```bash
|
|
83
|
+
pip install ultimate-gemini-mcp
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
#### Option 3: From Source
|
|
87
|
+
```bash
|
|
88
|
+
git clone <repository-url>
|
|
89
|
+
cd ultimate-gemini-mcp
|
|
90
|
+
uv sync
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
### Configuration
|
|
94
|
+
|
|
95
|
+
Create a `.env` file in your project directory:
|
|
96
|
+
```bash
|
|
97
|
+
cp .env.example .env
|
|
98
|
+
# Edit .env and add your GEMINI_API_KEY
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Or set environment variables directly:
|
|
102
|
+
```bash
|
|
103
|
+
export GEMINI_API_KEY=your_api_key_here
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
## 📖 Usage
|
|
107
|
+
|
|
108
|
+
### With Claude Desktop
|
|
109
|
+
|
|
110
|
+
Add to your `claude_desktop_config.json`:
|
|
111
|
+
|
|
112
|
+
```json
|
|
113
|
+
{
|
|
114
|
+
"mcpServers": {
|
|
115
|
+
"ultimate-gemini": {
|
|
116
|
+
"command": "uvx",
|
|
117
|
+
"args": ["ultimate-gemini-mcp"],
|
|
118
|
+
"env": {
|
|
119
|
+
"GEMINI_API_KEY": "your-api-key-here"
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
**Config file locations:**
|
|
127
|
+
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
128
|
+
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
129
|
+
|
|
130
|
+
### With Claude Code (VS Code)
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
# Add MCP server to Claude Code
|
|
134
|
+
claude mcp add ultimate-gemini --env GEMINI_API_KEY=your-api-key -- uvx ultimate-gemini-mcp
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
### With Cursor
|
|
138
|
+
|
|
139
|
+
Add to Cursor's MCP configuration (`.cursor/mcp.json`):
|
|
140
|
+
|
|
141
|
+
```json
|
|
142
|
+
{
|
|
143
|
+
"mcpServers": {
|
|
144
|
+
"ultimate-gemini": {
|
|
145
|
+
"command": "uvx",
|
|
146
|
+
"args": ["ultimate-gemini-mcp"],
|
|
147
|
+
"env": {
|
|
148
|
+
"GEMINI_API_KEY": "your-api-key-here"
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
## 🎯 Available Models
|
|
156
|
+
|
|
157
|
+
### Gemini Models
|
|
158
|
+
- **gemini-2.5-flash-image** (default): Advanced image generation with prompt enhancement and editing
|
|
159
|
+
|
|
160
|
+
### Imagen Models
|
|
161
|
+
- **imagen-4**: High-quality image generation with improved text rendering
|
|
162
|
+
- **imagen-4-fast**: Optimized for faster generation with good quality
|
|
163
|
+
- **imagen-4-ultra**: Highest quality with best prompt adherence and professional results
|
|
164
|
+
|
|
165
|
+
## 🛠️ Tools
|
|
166
|
+
|
|
167
|
+
### `generate_image`
|
|
168
|
+
|
|
169
|
+
Generate images using any supported model with comprehensive parameters.
|
|
170
|
+
|
|
171
|
+
**Parameters:**
|
|
172
|
+
- `prompt` (required): Text description of the image
|
|
173
|
+
- `model`: Model to use (default: gemini-2.5-flash-image)
|
|
174
|
+
- `enhance_prompt`: Automatically enhance prompt (default: true)
|
|
175
|
+
- `number_of_images`: Number of images to generate, 1-4 (default: 1)
|
|
176
|
+
- `aspect_ratio`: Aspect ratio like 1:1, 16:9, 9:16 (default: 1:1)
|
|
177
|
+
- `output_format`: Image format: png, jpeg, webp (default: png)
|
|
178
|
+
|
|
179
|
+
**Gemini-Specific Parameters:**
|
|
180
|
+
- `input_image_path`: Path to input image for editing
|
|
181
|
+
- `maintain_character_consistency`: Maintain character features across generations
|
|
182
|
+
- `blend_images`: Enable multi-image blending
|
|
183
|
+
- `use_world_knowledge`: Use real-world knowledge for context
|
|
184
|
+
|
|
185
|
+
**Imagen-Specific Parameters:**
|
|
186
|
+
- `person_generation`: Person policy: dont_allow, allow_adult, allow_all
|
|
187
|
+
- `negative_prompt`: What to avoid in the image
|
|
188
|
+
- `seed`: Random seed for reproducibility
|
|
189
|
+
|
|
190
|
+
**Example:**
|
|
191
|
+
```
|
|
192
|
+
Generate an image of "a serene mountain landscape at sunset with a lake reflection" using imagen-4-ultra
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
### `batch_generate`
|
|
196
|
+
|
|
197
|
+
Process multiple prompts efficiently with parallel batch processing.
|
|
198
|
+
|
|
199
|
+
**Parameters:**
|
|
200
|
+
- `prompts` (required): List of text prompts
|
|
201
|
+
- `model`: Model to use for all images
|
|
202
|
+
- `enhance_prompt`: Enhance all prompts (default: true)
|
|
203
|
+
- `aspect_ratio`: Aspect ratio for all images
|
|
204
|
+
- `batch_size`: Parallel processing size (default: from config)
|
|
205
|
+
|
|
206
|
+
**Example:**
|
|
207
|
+
```
|
|
208
|
+
Batch generate images for these prompts:
|
|
209
|
+
1. "minimalist logo design for a tech startup"
|
|
210
|
+
2. "modern dashboard UI design"
|
|
211
|
+
3. "mobile app wireframe"
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
## 🎨 Advanced Features
|
|
215
|
+
|
|
216
|
+
### AI Prompt Enhancement
|
|
217
|
+
|
|
218
|
+
When enabled (default), the server uses Gemini Flash to automatically enhance your prompts:
|
|
219
|
+
|
|
220
|
+
**Original:** `a cat wearing a space helmet`
|
|
221
|
+
|
|
222
|
+
**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`
|
|
223
|
+
|
|
224
|
+
This significantly improves image quality without requiring you to be a prompt engineering expert!
|
|
225
|
+
|
|
226
|
+
### Image Editing
|
|
227
|
+
|
|
228
|
+
Use natural language to edit existing images (Gemini model):
|
|
229
|
+
|
|
230
|
+
```
|
|
231
|
+
Generate an image with:
|
|
232
|
+
- prompt: "Add a red scarf to the person"
|
|
233
|
+
- input_image_path: "/path/to/image.jpg"
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
### Character Consistency
|
|
237
|
+
|
|
238
|
+
Generate the same character in different scenes:
|
|
239
|
+
|
|
240
|
+
```
|
|
241
|
+
Generate an image of "a young wizard in a library, studying ancient books"
|
|
242
|
+
with maintain_character_consistency: true
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
Then:
|
|
246
|
+
```
|
|
247
|
+
Generate an image of "the same young wizard, now in a magical forest"
|
|
248
|
+
with maintain_character_consistency: true
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
### Reproducible Results
|
|
252
|
+
|
|
253
|
+
Use seeds for consistent generation (Imagen models):
|
|
254
|
+
|
|
255
|
+
```
|
|
256
|
+
Generate an image with:
|
|
257
|
+
- prompt: "a futuristic cityscape"
|
|
258
|
+
- model: "imagen-4-ultra"
|
|
259
|
+
- seed: 42
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
Running with the same seed will produce the same image.
|
|
263
|
+
|
|
264
|
+
## ⚙️ Configuration
|
|
265
|
+
|
|
266
|
+
### Environment Variables
|
|
267
|
+
|
|
268
|
+
| Variable | Description | Default |
|
|
269
|
+
|----------|-------------|---------|
|
|
270
|
+
| `GEMINI_API_KEY` | Google Gemini API key (required) | - |
|
|
271
|
+
| `OUTPUT_DIR` | Directory for generated images | `generated_images` |
|
|
272
|
+
| `ENABLE_PROMPT_ENHANCEMENT` | Enable AI prompt enhancement | `true` |
|
|
273
|
+
| `ENABLE_BATCH_PROCESSING` | Enable batch processing | `true` |
|
|
274
|
+
| `DEFAULT_GEMINI_MODEL` | Default Gemini model | `gemini-2.5-flash-image` |
|
|
275
|
+
| `DEFAULT_IMAGEN_MODEL` | Default Imagen model | `imagen-4-ultra` |
|
|
276
|
+
| `REQUEST_TIMEOUT` | API request timeout (seconds) | `60` |
|
|
277
|
+
| `MAX_BATCH_SIZE` | Maximum parallel batch size | `8` |
|
|
278
|
+
| `LOG_LEVEL` | Logging level | `INFO` |
|
|
279
|
+
|
|
280
|
+
## 📚 MCP Resources
|
|
281
|
+
|
|
282
|
+
### `models://list`
|
|
283
|
+
View all available models with descriptions and features.
|
|
284
|
+
|
|
285
|
+
### `settings://config`
|
|
286
|
+
View current server configuration.
|
|
287
|
+
|
|
288
|
+
## 🎭 Use Cases
|
|
289
|
+
|
|
290
|
+
### Web Development
|
|
291
|
+
- Hero images and banners
|
|
292
|
+
- UI/UX mockups and wireframes
|
|
293
|
+
- Logo and branding assets
|
|
294
|
+
- Placeholder images
|
|
295
|
+
|
|
296
|
+
### App Development
|
|
297
|
+
- App icons and splash screens
|
|
298
|
+
- User interface elements
|
|
299
|
+
- Marketing materials
|
|
300
|
+
- Documentation images
|
|
301
|
+
|
|
302
|
+
### Content Creation
|
|
303
|
+
- Blog post illustrations
|
|
304
|
+
- Social media graphics
|
|
305
|
+
- Presentation visuals
|
|
306
|
+
- Product mockups
|
|
307
|
+
|
|
308
|
+
### Creative Projects
|
|
309
|
+
- Character design iterations
|
|
310
|
+
- Concept art exploration
|
|
311
|
+
- Style variations
|
|
312
|
+
- Scene composition
|
|
313
|
+
|
|
314
|
+
## 📊 Comparison
|
|
315
|
+
|
|
316
|
+
| Feature | Gemini 2.5 Flash | Imagen 4/Fast/Ultra |
|
|
317
|
+
|---------|------------------|---------------------|
|
|
318
|
+
| Prompt Enhancement | ✅ Built-in | ✅ Built-in |
|
|
319
|
+
| Image Editing | ✅ Yes | ❌ No |
|
|
320
|
+
| Character Consistency | ✅ Yes | ❌ No |
|
|
321
|
+
| Multi-Image Blending | ✅ Yes | ❌ No |
|
|
322
|
+
| Negative Prompts | ❌ No | ✅ Yes |
|
|
323
|
+
| Seed-based Reproducibility | ❌ No | ✅ Yes |
|
|
324
|
+
| Person Generation Controls | ❌ No | ✅ Yes |
|
|
325
|
+
| Speed Options | Standard | Fast/Standard/Ultra |
|
|
326
|
+
| Best For | Editing, iteration, context-aware | Photorealism, final quality, speed |
|
|
327
|
+
|
|
328
|
+
## 🐛 Troubleshooting
|
|
329
|
+
|
|
330
|
+
### "GEMINI_API_KEY not found"
|
|
331
|
+
- Add your API key to `.env` or environment variables
|
|
332
|
+
- Get a free key at [Google AI Studio](https://makersuite.google.com/app/apikey)
|
|
333
|
+
|
|
334
|
+
### "Content blocked by safety filters"
|
|
335
|
+
- Modify your prompt to comply with content policies
|
|
336
|
+
- Try rephrasing without potentially sensitive content
|
|
337
|
+
|
|
338
|
+
### "Rate limit exceeded"
|
|
339
|
+
- Wait a few moments and try again
|
|
340
|
+
- Consider upgrading your API plan for higher limits
|
|
341
|
+
|
|
342
|
+
### Images not saving
|
|
343
|
+
- Check that OUTPUT_DIR exists and is writable
|
|
344
|
+
- Verify you have sufficient disk space
|
|
345
|
+
|
|
346
|
+
## 🤝 Contributing
|
|
347
|
+
|
|
348
|
+
Contributions are welcome! This project combines the best features from multiple MCP servers:
|
|
349
|
+
- mcp-image (TypeScript): Prompt enhancement and editing features
|
|
350
|
+
- nanobanana-mcp-server (Python): Architecture and FastMCP integration
|
|
351
|
+
- gemini-imagen-mcp-server (TypeScript): Imagen API support and batch processing
|
|
352
|
+
|
|
353
|
+
## 📄 License
|
|
354
|
+
|
|
355
|
+
MIT License - see LICENSE file for details.
|
|
356
|
+
|
|
357
|
+
## 🙏 Acknowledgments
|
|
358
|
+
|
|
359
|
+
Built on the excellent work of:
|
|
360
|
+
- [mcp-image](https://github.com/shinpr/mcp-image) - Prompt enhancement concept
|
|
361
|
+
- [nanobanana-mcp-server](https://github.com/zhongweili/nanobanana-mcp-server) - FastMCP architecture
|
|
362
|
+
- [gemini-imagen-mcp-server](https://github.com/serkanhaslak/gemini-imagen-mcp-server) - Imagen integration
|
|
363
|
+
|
|
364
|
+
## 🔗 Links
|
|
365
|
+
|
|
366
|
+
- [Google AI Studio](https://makersuite.google.com/app/apikey) - Get your API key
|
|
367
|
+
- [Gemini API Documentation](https://ai.google.dev/gemini-api/docs)
|
|
368
|
+
- [Model Context Protocol](https://modelcontextprotocol.io/)
|
|
369
|
+
|
|
370
|
+
---
|
|
371
|
+
|
|
372
|
+
**Ready to create amazing AI-generated images?** Install now and start generating! 🚀
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
src/__init__.py,sha256=DNVyeC3hyUv0WJlXtrOXH-Miw4ee8ZDiCW6GwJnjPJo,435
|
|
2
|
+
src/server.py,sha256=vVJ96VMl-Z7y756qjASywZaD2QYj5v8nIQ8r504Mg3g,5877
|
|
3
|
+
src/config/__init__.py,sha256=hL0recV_ycXBEGCym7BqwyaPCnQHy8o429pBirnBeiA,704
|
|
4
|
+
src/config/constants.py,sha256=iLHMFVJzWRkSMkG6gXHBWepVLbcDvlgqZtkgfEuaaUQ,1877
|
|
5
|
+
src/config/settings.py,sha256=IxxvETiW-CK5VLeTOegx3hAfd5gIxBSVAUyKbc9GBpU,4332
|
|
6
|
+
src/core/__init__.py,sha256=h8ik58bFn0g0XFVtMEI4MDoFapi4FlQywgd3S0eR2Oo,1266
|
|
7
|
+
src/core/exceptions.py,sha256=U09aPGmlDTAGbt6PbF-PKbmT1ee9LHqghkOXGn094UI,1197
|
|
8
|
+
src/core/validation.py,sha256=NzF01GVhmBefn_bo4cGDMREuE6kc3RujbfOtfx9eLyk,5186
|
|
9
|
+
src/services/__init__.py,sha256=5iCkCasXmsBcJ0zDIu3qCSdTZtmKPDmWuz14dMK0N7I,395
|
|
10
|
+
src/services/gemini_client.py,sha256=nVhx2s8sVhizeHa1D6IbxT5TRqGIF23kobMTcBh5vyA,7490
|
|
11
|
+
src/services/image_service.py,sha256=UcErTYMjG6ihKeT2w0UaGiiVIoUwf2Kt7oSafEjx28w,7526
|
|
12
|
+
src/services/imagen_client.py,sha256=dvDa0Z6xV-xeF428_arf3JXMf-rYlwOXoDD_6pTZzOE,5660
|
|
13
|
+
src/services/prompt_enhancer.py,sha256=JFTKqwWafngq37yGjiYT5-FJbIj4Buvt0js2nU_9gsw,4805
|
|
14
|
+
src/tools/__init__.py,sha256=zBfAjFT51LvvD7WXTfDYiyJstRdphr2ChddAmGMZxkI,346
|
|
15
|
+
src/tools/batch_generate.py,sha256=tcilmaOWXMFnVBMdMbIUXxHtbpnBLeIkJe2LDXnE7qU,5200
|
|
16
|
+
src/tools/generate_image.py,sha256=7X23jAdxzyC4lWCmIu3tIcs807w3duDrZdGMb7cPpZE,8818
|
|
17
|
+
ultimate_gemini_mcp-1.0.1.dist-info/METADATA,sha256=R2TJ6uoVfF0q9541w7RUB5lFfWufVQ5HYvQNbT8ZKnU,11646
|
|
18
|
+
ultimate_gemini_mcp-1.0.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
|
|
19
|
+
ultimate_gemini_mcp-1.0.1.dist-info/entry_points.txt,sha256=-BeRTT4oR05e-YnF1ZNbNxlaekD4LsWhD-Zy_1dyRnc,56
|
|
20
|
+
ultimate_gemini_mcp-1.0.1.dist-info/licenses/LICENSE,sha256=ilyzUnN0QHYtYGJks-NFUwiniNu08IedLmn_muRqa0o,1480
|
|
21
|
+
ultimate_gemini_mcp-1.0.1.dist-info/RECORD,,
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Ultimate Gemini MCP Contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
This project combines and builds upon features from:
|
|
26
|
+
- mcp-image (https://github.com/shinpr/mcp-image)
|
|
27
|
+
- nanobanana-mcp-server (https://github.com/zhongweili/nanobanana-mcp-server)
|
|
28
|
+
- gemini-imagen-mcp-server (https://github.com/serkanhaslak/gemini-imagen-mcp-server)
|
|
29
|
+
|
|
30
|
+
Each of these projects has its own license. Please refer to their respective
|
|
31
|
+
repositories for their licensing terms.
|