Skip to main content
Glama

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

Related MCP server: Nano Banana MCP Server

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

# 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
# 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

# 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:

export NEXOS_API_KEY=your-api-key-here

Or create a .env file:

NEXOS_API_KEY=your-api-key-here

Usage

Running the Server

# 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):

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

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

{
  "mcpServers": {
    "imagen": {
      "command": "imagen-mcp",
      "env": {
        "NEXOS_API_KEY": "your-nexos-api-key-here"
      }
    }
  }
}

Generic MCP Client (Copy-Paste Ready)

For pipx/pip installation:

{
  "imagen": {
    "command": "imagen-mcp",
    "env": {
      "NEXOS_API_KEY": "your-nexos-api-key-here"
    }
  }
}

For Poetry installation:

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

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

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

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:

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:

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:

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

# 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

Available Tools

6 tools
generate_imageB

Generate a single image from a text prompt.

Args: prompt: Text description of the image to generate. model: Model to use (imagen-4, imagen-4-fast, imagen-4-ultra, flux-1.1-pro, gpt-image-1). size: Image size (256x256, 512x512, 1024x1024, 1792x1024, 1024x1792). quality: Image quality (standard, hd). style: Image style (vivid, natural).

Returns: Dictionary with success status, file path, and metadata.

Inputs: prompt (required), model, size, quality, +1 more. Returns: object

get_batch_statusA

Get the current status of a batch generation session.

Args: session_id: Session ID from start_image_batch.

Returns: Dictionary with session status, completed/pending counts, and errors.

Inputs: session_id (required). Returns: object

get_model_detailsA

Get detailed information about a specific image generation model.

Args: model_id: The model identifier (e.g., 'imagen-4', 'imagen-4-fast', 'dall-e-3').

Returns: Dictionary with complete model details including capabilities, rate limits, use cases, strengths, and weaknesses. Returns an error if the model is not found.

Inputs: model_id (required). Returns: object

get_next_imageA

Get the next available image from a batch generation session.

This tool retrieves the next image from an ongoing batch generation. If an image is already available, it returns immediately. Otherwise, it blocks until an image becomes available or timeout.

Args: session_id: Session ID from start_image_batch. timeout: Maximum time to wait for an image (seconds, 1-300).

Returns: Dictionary with file_path, has_more flag, and pending_count.

Inputs: session_id (required), timeout. Returns: object

list_modelsA

List all available image generation models with their descriptions.

Returns a comprehensive list of all available models including:

  • Model ID and display name

  • Provider (Google, OpenAI, etc.)

  • Description and intended use cases

  • Strengths and weaknesses

  • Supported image sizes

  • Rate limits and capabilities

Use this tool to discover which models are available and choose the best one for your image generation needs.

Returns: Dictionary with models list and default model information.

Inputs: no named parameters. Returns: object

start_image_batchA

Start generating multiple images and return the first one.

This tool starts generating multiple images in the background. It blocks until the first image is ready, then returns it along with a session ID for retrieving the remaining images.

Args: prompt: Text description of the image to generate. count: Number of images to generate (2-10). model: Model to use for generation. size: Image size. quality: Image quality (standard, hd). style: Image style (vivid, natural).

Returns: Dictionary with session_id, first_image_path, and pending_count.

Inputs: prompt (required), count, model, size, +2 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no ambiguity. generate_image creates single images, start_image_batch handles batch generation, get_next_image retrieves batch results, get_batch_status checks batch progress, list_models enumerates available models, and get_model_details provides specific model information. The tools cover different aspects of the image generation workflow without overlap.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with snake_case throughout. The naming is predictable and readable: generate_image, start_image_batch, get_next_image, get_batch_status, list_models, and get_model_details. This consistency makes it easy for agents to understand the tool purposes from their names alone.

    Tool Count5/5

    Six tools is well-scoped for an image generation server. Each tool earns its place by covering distinct aspects of the workflow: single generation, batch generation, batch retrieval, status checking, model listing, and model details. This count provides comprehensive coverage without being overwhelming or too sparse for the domain.

    Completeness5/5

    The tool surface provides complete coverage for image generation workflows. It supports both single and batch generation, includes status monitoring and result retrieval for batches, and offers comprehensive model discovery and information tools. There are no obvious gaps—agents can generate images, track progress, retrieve results, and make informed model selections.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers