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 for package management
• Google Cloud credentials (see Authentication)

Installation

1. Clone the Repository

git clone https://github.com/anton-proto/mcp-imagen.git
cd mcp-imagen/mcp-imagen-server

2. Install with uv

# 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
2. Set the API key:

   export GOOGLE_API_KEY="your-api-key-here"
   

Option B: Using Vertex AI (Recommended for production)

1. Install Google Cloud SDK:

   # For Debian/Ubuntu
   curl https://sdk.cloud.google.com | bash
   exec -l $SHELL
   

2. Authenticate with Google Cloud:

   gcloud auth application-default login
   

3. Set your project:

   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

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:

{
  "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:

{
  "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)
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 for linting and formatting:

# 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

# 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
• Vertex AI Imagen API
• Model Context Protocol
• Google Gen AI Python SDK