# Imagen MCP Server
A Model Context Protocol (MCP) server for image generation using Google's Imagen model and other models supported by the Nexos.ai platform.
## Features
- **Simple Image Generation**: Generate a single image from a text prompt
- **Batch Image Generation**: Generate multiple images with background processing
- First image is returned immediately
- Remaining images are generated in the background
- Query for additional images as they become available
- **Model Catalog**: Access comprehensive information about all available models
## Supported Models
| Model | Provider | Description |
|-------|----------|-------------|
| `imagen-4` | Google | Flagship model with excellent prompt following and photorealistic output |
| `imagen-4-fast` | Google | Faster variant optimized for speed |
| `imagen-4-ultra` | Google | Highest quality for premium image generation |
| `dall-e-3` | OpenAI | High-quality model with excellent artistic capabilities |
| `gpt-image-1` | OpenAI | Strong prompt understanding and versatile output |
## Installation
### Option 1: Install with pipx (Recommended for CLI usage)
```bash
# Install directly from the repository
pipx install git+https://github.com/your-username/Imagen-MCP.git
# Or install from local directory
cd Imagen-MCP
pipx install .
# Run the server
imagen-mcp
```
### Option 2: Install with Poetry (Recommended for development)
```bash
# Clone the repository
git clone <repository-url>
cd Imagen-MCP
# Install dependencies with Poetry
poetry install
# Run the server
poetry run imagen-mcp
# Or
poetry run python -m Imagen_MCP.server
```
### Option 3: Install with pip
```bash
# Install from the repository
pip install git+https://github.com/your-username/Imagen-MCP.git
# Or install from local directory
pip install .
# Run the server
imagen-mcp
```
### Environment Variables
Set up your Nexos.ai API key:
```bash
export NEXOS_API_KEY=your-api-key-here
```
Or create a `.env` file:
```env
NEXOS_API_KEY=your-api-key-here
```
## Usage
### Running the Server
```bash
# If installed with pipx or pip
imagen-mcp
# If using Poetry (development)
poetry run imagen-mcp
# Alternative: run as Python module
poetry run python -m Imagen_MCP.server
# With FastMCP CLI (more options)
poetry run fastmcp run Imagen_MCP/server.py --transport http --port 8000
```
### CLI Options
When using the `fastmcp run` command, you have additional options:
| Option | Description |
|--------|-------------|
| `--transport`, `-t` | Transport protocol: `stdio` (default), `http`, `sse`, `streamable-http` |
| `--host` | Host to bind to (default: 127.0.0.1) |
| `--port`, `-p` | Port for HTTP/SSE transport (default: 8000) |
| `--log-level`, `-l` | Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL |
| `--no-banner` | Don't show the server banner |
### MCP Client Configuration
To use this MCP server with an AI agent, add the following configuration to your MCP client.
#### Claude Desktop (pipx installation)
If you installed with pipx, add to your Claude Desktop configuration file (`~/.config/claude/claude_desktop_config.json` on Linux, `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"imagen": {
"command": "imagen-mcp",
"env": {
"NEXOS_API_KEY": "your-nexos-api-key-here"
}
}
}
}
```
#### Claude Desktop (Poetry installation)
If you're using Poetry for development:
```json
{
"mcpServers": {
"imagen": {
"command": "poetry",
"args": ["run", "imagen-mcp"],
"cwd": "/path/to/Imagen-MCP",
"env": {
"NEXOS_API_KEY": "your-nexos-api-key-here"
}
}
}
}
```
#### Cline / Roo Code
Add to your VS Code settings or Cline MCP configuration:
```json
{
"mcpServers": {
"imagen": {
"command": "imagen-mcp",
"env": {
"NEXOS_API_KEY": "your-nexos-api-key-here"
}
}
}
}
```
#### Generic MCP Client (Copy-Paste Ready)
For pipx/pip installation:
```json
{
"imagen": {
"command": "imagen-mcp",
"env": {
"NEXOS_API_KEY": "your-nexos-api-key-here"
}
}
}
```
For Poetry installation:
```json
{
"imagen": {
"command": "poetry",
"args": ["run", "imagen-mcp"],
"cwd": "/path/to/Imagen-MCP",
"env": {
"NEXOS_API_KEY": "your-nexos-api-key-here"
}
}
}
```
**Configuration Options:**
| Field | Description |
|-------|-------------|
| `command` | The command to run (`poetry` for Poetry-managed projects) |
| `args` | Command arguments to start the MCP server |
| `cwd` | Working directory - set to your Imagen-MCP installation path |
| `env` | Environment variables, including the required `NEXOS_API_KEY` |
**Important:** Replace `/path/to/Imagen-MCP` with the actual path to your Imagen-MCP installation and `your-nexos-api-key-here` with your Nexos.ai API key.
#### Alternative: Using pip-installed package
If you install the package globally or in a virtual environment:
```json
{
"imagen": {
"command": "python",
"args": ["-m", "Imagen_MCP.server"],
"env": {
"NEXOS_API_KEY": "your-nexos-api-key-here"
}
}
}
```
## Tools
### `list_models`
List all available image generation models with their descriptions, capabilities, and use cases.
**Parameters:** None
**Returns:**
- `models`: List of all available models with details
- `total_count`: Number of available models
- `default_model`: The default model ID
- `usage_hint`: How to use the model parameter
**Example Response:**
```json
{
"models": [
{
"id": "imagen-4",
"name": "Imagen 4",
"provider": "Google",
"description": "Google's flagship image generation model...",
"use_cases": ["Photorealistic image generation", ...],
"strengths": ["Excellent prompt adherence", ...],
"weaknesses": ["Slower generation time", ...],
"supported_sizes": ["256x256", "512x512", "1024x1024", ...],
"max_images_per_request": 4,
"supports_hd_quality": true,
"rate_limit": "100 messages per 3 hours"
},
...
],
"total_count": 5,
"default_model": "imagen-4"
}
```
### `get_model_details`
Get detailed information about a specific image generation model.
**Parameters:**
- `model_id` (required): The model identifier (e.g., "imagen-4", "imagen-4-fast", "dall-e-3")
**Returns:**
- Complete model details including capabilities, rate limits, use cases, strengths, and weaknesses
- Error message if model not found
**Example:**
```python
result = get_model_details(model_id="imagen-4-fast")
```
### `generate_image`
Generate a single image from a text prompt. The image is saved to a file (temporary file if no path specified).
**Parameters:**
- `prompt` (required): Text description of the image to generate
- `model` (optional): Model to use (default: "imagen-4")
- `size` (optional): Image size (default: "1024x1024")
- `quality` (optional): Image quality - "standard" or "hd" (default: "standard")
- `style` (optional): Image style - "vivid" or "natural" (default: "vivid")
**Returns:**
- `success`: Whether the image was generated successfully
- `file_path`: Absolute path to the saved image file
- `file_size_bytes`: Size of the saved image file in bytes
- `model_used`: The model that was used for generation
- `revised_prompt`: The revised prompt (if the model modified it)
- `error`: Error message if generation failed
**Example:**
```python
result = await generate_image(
prompt="A serene mountain landscape at sunset",
model="imagen-4",
size="1024x1024",
quality="hd",
style="natural"
)
if result.success:
print(f"Image saved to: {result.file_path}")
print(f"File size: {result.file_size_bytes} bytes")
```
### `start_image_batch`
Start generating multiple images and return the first one immediately. Images are saved to files (in a temporary directory if no path specified).
**Parameters:**
- `prompt` (required): Text description of the image to generate
- `count` (optional): Number of images to generate, 2-10 (default: 4)
- `model` (optional): Model to use (default: "imagen-4")
- `size` (optional): Image size (default: "1024x1024")
- `quality` (optional): Image quality (default: "standard")
- `style` (optional): Image style (default: "vivid")
**Returns:**
- `success`: Whether the batch was started successfully
- `session_id`: ID for retrieving more images
- `first_image_path`: Path to the first generated image file
- `first_image_size_bytes`: Size of the first image file in bytes
- `pending_count`: Number of images still being generated
- `error`: Error message if batch failed to start
**Example:**
```python
result = await start_image_batch(
prompt="A futuristic cityscape",
count=5,
model="imagen-4"
)
if result.success:
print(f"Session ID: {result.session_id}")
print(f"First image: {result.first_image_path}")
```
### `get_next_image`
Get the next available image from a batch generation session. The image is saved to a file (temporary file if no path specified).
**Parameters:**
- `session_id` (required): Session ID from start_image_batch
- `timeout` (optional): Maximum wait time in seconds (default: 60)
**Returns:**
- `success`: Whether an image was retrieved
- `file_path`: Path to the saved image file (or null if no image available)
- `file_size_bytes`: Size of the saved image file in bytes
- `has_more`: Whether more images are available or pending
- `pending_count`: Number of images still being generated
- `error`: Error message if retrieval failed
**Example:**
```python
while True:
result = await get_next_image(session_id=session_id)
if result.file_path:
print(f"Image saved to: {result.file_path}")
if not result.has_more:
break
```
### `get_batch_status`
Get the current status of a batch generation session.
**Parameters:**
- `session_id` (required): Session ID from start_image_batch
**Returns:**
- `status`: Session status (created, generating, partial, completed, failed)
- `completed_count`: Number of completed images
- `pending_count`: Number of pending images
- `total_count`: Total number of requested images
- `errors`: List of any errors encountered
## Resources
### `models://image-generation`
Get the complete catalog of available image generation models with their capabilities, rate limits, use cases, strengths, and weaknesses.
### `models://image-generation/{model_id}`
Get detailed information about a specific model.
## Development
### Running Tests
```bash
# Run all tests
poetry run pytest
# Run with verbose output
poetry run pytest -v
# Run specific test file
poetry run pytest tests/unit/test_generate_image.py
```
### Project Structure
```
Imagen_MCP/
├── __init__.py # Package exports
├── server.py # FastMCP server definition
├── config.py # Configuration management
├── constants.py # Constants and type definitions
├── exceptions.py # Custom exceptions
├── tools/
│ ├── generate_image.py # Simple image generation tool
│ └── batch_generate.py # Batch generation tools
├── resources/
│ └── models.py # Model catalog resource
├── services/
│ ├── nexos_client.py # Nexos.ai API client
│ ├── session_manager.py # Background generation session manager
│ └── model_registry.py # Model information registry
└── models/
├── image.py # Image data models
├── generation.py # Generation request/response models
└── session.py # Session state models
```
## Rate Limits
All models are in Category 3 on Nexos.ai:
- 100 messages per 3 hours
## License
MIT License
