# MCP Imagen Server
An MCP (Model Context Protocol) server for Google Imagen API, enabling text-to-image generation using Google's state-of-the-art Imagen models.
## Features
- **Text-to-Image Generation**: Generate high-quality images from text prompts using Imagen 4.0 models
- **Style Transfer**: Generate images following the style of a reference image using Imagen 3 Customization
- **Background Removal**: Remove backgrounds from images using rembg AI model
- **Auto-Crop**: Automatically crop images to remove transparent or empty borders with batch processing support
- **Multiple Models**: Support for three Imagen variants:
- `imagen-4.0-generate-001` (default) - Standard quality and speed
- `imagen-4.0-fast-generate-001` - Faster generation
- `imagen-4.0-ultra-generate-001` - Highest quality (single image only)
- **Flexible Configuration**:
- Customizable aspect ratios (1:1, 3:4, 4:3, 9:16, 16:9)
- Batch generation (1-4 images per request)
- PNG output format with transparency support
- **Authentication Options**:
- Google Cloud Default Application Credentials
- Vertex AI or Gemini API
## Prerequisites
- Python 3.11 or later
- [uv](https://github.com/astral-sh/uv) for package management
- Google Cloud credentials (see [Authentication](#authentication))
## Installation
### 1. Clone the Repository
```bash
git clone https://github.com/anton-proto/mcp-imagen.git
cd mcp-imagen/mcp-imagen-server
```
### 2. Install with uv
```bash
# Install dependencies
uv sync
# Or install in development mode
uv sync --all-extras
```
### 3. Set Up Authentication
#### Option A: Using Gemini API (Recommended for quick start)
1. Get an API key from [Google AI Studio](https://aistudio.google.com/apikey)
2. Set the API key:
```bash
export GOOGLE_API_KEY="your-api-key-here"
```
#### Option B: Using Vertex AI (Recommended for production)
1. Install Google Cloud SDK:
```bash
# For Debian/Ubuntu
curl https://sdk.cloud.google.com | bash
exec -l $SHELL
```
2. Authenticate with Google Cloud:
```bash
gcloud auth application-default login
```
3. Set your project:
```bash
export GOOGLE_CLOUD_PROJECT="your-project-id"
export USE_VERTEXAI="true"
# Optional: specify location (default: us-central1)
export GOOGLE_CLOUD_LOCATION="us-central1"
```
## Usage
### Running the Server
```bash
uv run mcp-imagen-server
```
The server will start and listen for MCP requests via stdio.
### Integration with Claude Desktop
Add this configuration to your Claude Desktop config file:
**Location**:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
**Configuration**:
```json
{
"mcpServers": {
"imagen": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/mcp-imagen-server",
"run",
"mcp-imagen-server"
],
"env": {
"GOOGLE_API_KEY": "your-api-key-here"
}
}
}
}
```
**For Vertex AI**:
```json
{
"mcpServers": {
"imagen": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/mcp-imagen-server",
"run",
"mcp-imagen-server"
],
"env": {
"USE_VERTEXAI": "true",
"GOOGLE_CLOUD_PROJECT": "your-project-id",
"GOOGLE_CLOUD_LOCATION": "us-central1"
}
}
}
}
```
### Integration with Other MCP Clients
The server implements the standard MCP protocol and can be used with any MCP-compatible client.
## MCP Tools
### text-to-image
Generates images from text prompts using Google Imagen API.
### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | Yes | - | Text description of the image to generate |
| `output_dir` | string | Yes | - | Absolute path to directory where images should be saved |
| `model` | string | No | `imagen-4.0-generate-001` | Imagen model to use (see [Models](#models)) |
| `sample_count` | integer | No | 1 | Number of images to generate (1-4, must be 1 for ultra model) |
| `aspect_ratio` | string | No | `1:1` | Aspect ratio of generated images (1:1, 3:4, 4:3, 9:16, 16:9) |
### Models
- **imagen-4.0-generate-001**: Standard model with balanced quality and speed
- **imagen-4.0-fast-generate-001**: Faster generation with good quality
- **imagen-4.0-ultra-generate-001**: Highest quality, single image only (sample_count must be 1)
### Response
Returns a text response with paths to generated PNG files:
```
Successfully generated 2 image(s):
1. /path/to/output/A_serene_mountain_landscape_at_sunset_1.png
2. /path/to/output/A_serene_mountain_landscape_at_sunset_2.png
```
### Example Usage
In Claude Desktop or other MCP client:
```
Generate an image of "A serene mountain landscape at sunset with a lake reflecting the sky" and save it to /tmp/images/
```
### style-to-image
Generates images following the style of a reference image using Imagen 3 Customization.
#### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image content to generate |
| `style_image_path` | string | Yes | Absolute path to the style reference image file |
| `style_description` | string | Yes | Description of the style (e.g., "watercolor painting style", "neon sign style", "mosaic style") |
| `output_dir` | string | Yes | Absolute path to directory where images should be saved |
| `sample_count` | integer | No | Number of images to generate (1-4). Default: 1 |
#### Response
Returns a text response with paths to generated styled PNG files.
#### Example Usage
```
Generate an image of "A cat sitting on a windowsill" in the style of the image at /path/to/watercolor.png (watercolor painting style) and save it to /tmp/images/
```
### remove-background
Removes the background from an image using the rembg AI model, producing a PNG with transparent background.
#### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `input_path` | string | Yes | Absolute path to the input image file |
| `output_path` | string | No | Absolute path to save the output image. If not provided, will save with 'nobg_' prefix in same directory |
#### Response
Returns a text response with the path to the output image with transparent background:
```
Successfully removed background from image:
Output: /path/to/output/nobg_image.png
```
#### Example Usage
```
Remove the background from /home/user/images/photo.png
```
Or with custom output path:
```
Remove the background from /home/user/images/photo.png and save it to /home/user/outputs/transparent.png
```
### autocrop
Automatically crop images to remove transparent or empty borders. Supports both single image and batch processing with parallel execution.
#### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `input_paths` | array of strings | Yes | List of absolute paths to input image files to crop |
| `output_dir` | string | No | Absolute path to output directory. If not provided, cropped images will be saved in the same directory as input files with '_cropped' suffix |
| `padding` | integer | No | Number of pixels to add as padding around cropped content. Default: 0 |
| `overwrite` | boolean | No | Whether to overwrite existing output files. Default: True. If False and output file exists, the operation will fail with an error |
#### Response
Returns a text response with processing summary and paths to cropped images:
```
Processed 3 image(s):
Successfully cropped: 3
Cropped images:
1. /output/dir/image1_cropped.png
2. /output/dir/image2_cropped.png
3. /output/dir/image3_cropped.png
```
If any images fail to process, they will be listed separately:
```
Processed 3 image(s):
Successfully cropped: 2
Cropped images:
1. /output/dir/image1_cropped.png
2. /output/dir/image2_cropped.png
Failed: 1
- image3.png: Error: Image appears to be completely transparent or empty - cannot autocrop
```
#### Features
- **Parallel Processing**: Multiple images are processed concurrently for better performance
- **Batch Support**: Process multiple images in a single call
- **Flexible Output**: Save to a specific directory or use default location
- **Padding Control**: Add padding around cropped content if needed
- **Transparency Aware**: Automatically detects and crops around non-transparent pixels
#### Example Usage
Single image:
```
Autocrop the image at /home/user/images/logo.png
```
Multiple images with output directory:
```
Autocrop these images: ["/home/user/images/logo1.png", "/home/user/images/logo2.png", "/home/user/images/logo3.png"] and save to /home/user/cropped/
```
With padding:
```
Autocrop /home/user/images/logo.png with 10 pixels of padding and save to /home/user/output/
```
With overwrite disabled (prevent overwriting):
```
Autocrop /home/user/images/logo.png and save to /home/user/output/ with overwrite disabled
```
Note: By default, the tool will overwrite existing output files. Set `overwrite=False` to prevent accidental overwrites and raise an error if the output file already exists.
## Development
### Project Structure
```
mcp-imagen-server/
├── src/
│ └── mcp_imagen_server/
│ ├── __init__.py # Package initialization
│ ├── imagen_client.py # Imagen API client
│ └── server.py # MCP server implementation
├── pyproject.toml # Project configuration
├── README.md # This file
└── .python-version # Python version
```
### Code Quality
The project uses [ruff](https://github.com/astral-sh/ruff) for linting and formatting:
```bash
# Check code
uv run ruff check src/
# Format code
uv run ruff format src/
# Auto-fix issues
uv run ruff check --fix src/
```
### Running Tests
```bash
# Run tests (when implemented)
uv run pytest
```
## Environment Variables
| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `GOOGLE_API_KEY` | Google AI API key for Gemini API | For Gemini API | - |
| `USE_VERTEXAI` | Set to "true" to use Vertex AI | No | false |
| `GOOGLE_CLOUD_PROJECT` | GCP project ID | For Vertex AI | - |
| `GOOGLE_CLOUD_LOCATION` | GCP region | No | us-central1 |
## Troubleshooting
### Authentication Issues
**Problem**: `DefaultCredentialsError` or authentication failures
**Solution**:
- For Gemini API: Ensure `GOOGLE_API_KEY` is set
- For Vertex AI: Run `gcloud auth application-default login`
- Verify your project has the Vertex AI API enabled
### Permission Denied
**Problem**: Cannot write to output directory
**Solution**: Ensure the specified `output_dir` exists and is writable, or the server has permissions to create it
### Model Not Available
**Problem**: Model not found or access denied
**Solution**:
- Verify your Google Cloud project has access to Imagen models
- Check that you're using a supported model name
- For ultra model, ensure `sample_count=1`
## License
MIT License - See LICENSE file for details
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## References
- [Google Imagen Documentation](https://ai.google.dev/gemini-api/docs/imagen)
- [Vertex AI Imagen API](https://cloud.google.com/vertex-ai/generative-ai/docs/models/imagen/4-0-generate)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Google Gen AI Python SDK](https://github.com/googleapis/python-genai)
