Imagen MCP Server

How to use

You will run the MCP server locally and connect to it with an MCP client. Start by choosing a model for your image generation, then request single images or initiate a batch to generate multiple images with progress updates.

- Generate a single image by sending a prompt to the server using your MCP client. You can specify the size, quality, and style to influence the output.

- Start a batch to generate several images. The first result is returned immediately, while remaining images are produced in the background. You can poll for the next available image as they complete.

- Use the model catalog to learn about each available model, including its strengths, typical use cases, and any limitations.

How to install

Prerequisites you need before installing include Python and a package manager. You can install the server in several ways depending on your preference for tooling.

# Option 1: Install with pipx (CLI usage)
# Install directly from the repository
pipx install git+https://github.com/your-username/Imagen-MCP.git

# Or install from a local directory
cd Imagen-MCP
pipx install .

# Run the server
imagen-mcp

# Option 2: Install with Poetry (development)
# Clone the repository
git clone <repository-url>
cd Imagen-MCP

# Install dependencies with Poetry
poetry install

# Run the server
a) poetry run imagen-mcp
b) 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 your Nexos.ai API key to enable access to model services.

export NEXOS_API_KEY=your-api-key-here

Running the server

After installation, start the server using one of the supported methods. Pick the approach that matches your installation method.

# 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

Model catalog and tools

Explore the available image generation models and their capabilities. You can list models, view details for a specific model, and perform image generation tasks.

API-like tools and endpoints

The server exposes intuitive tools to interact with image generation features. You can list models, get model details, generate a single image, start a batch, fetch the next image in a batch, and check batch status.

Notes and troubleshooting

- Ensure your Nexos.ai API key is valid and set in your environment before making requests. - If a batch takes longer than expected, verify network connectivity and the model’s processing load. You can retry fetching the next image in the batch using the provided session ID.

list_models

List all available image generation models with details such as id, provider, description, use cases, strengths, and limitations.

get_model_details

Retrieve detailed information about a specific model by model_id, including capabilities and limits.

generate_image

Generate a single image from a text prompt using a chosen model, size, quality, and style.

start_image_batch

Initiate generation of multiple images from a prompt, returning the first image immediately and providing a session ID for subsequent images.

get_next_image

Fetch the next available image in a running batch using the session ID.

get_batch_status

Query the current status of a batch generation session, including counts and errors.