AI Image Generate

An MCP (Model Context Protocol) server implementation for generating images using Replicate's models.

This tool can be executed as a command-line application ai-image-generate.

Features

• Generate images from text prompts
• Configurable image parameters (resolution, aspect ratio, quality)
• Save generated images to specified directory
• Full MCP protocol compliance
• Error handling and validation
• Caching of generated images
• Retry mechanism for image downloads
• Concurrent image downloads
• Atomic file writes

Prerequisites

• Node.js 16+
• Replicate API token

Setup

1. Clone the repository
2. Install dependencies:

   npm install

3. Build the project:

   npm run build

4. Install the package globally to use the CLI command:

   npm install -g .

Usage

After installation, you can use the ai-image-generate command. The server listens for MCP requests on standard I/O.

Environment Variables

• REPLICATE_API_TOKEN (required): Your API token from Replicate.
• REPLICATE_MODEL (optional): The Replicate model to use. Defaults to black-forest-labs/flux-schnell.

Running the server

To run the server, execute the command in your terminal. You must provide the REPLICATE_API_TOKEN.

export REPLICATE_API_TOKEN="your-replicate-api-token-here"
export REPLICATE_MODEL="black-forest-labs/flux-schnell" # optional
ai-image-generate

To use with a client like Cursor:

1. Go to Settings -> Features -> MCP Servers.
2. Click "Add new MCP Server".
3. Set Type to "Command".
4. Set Command to: ai-image-generate
5. Set Environment Variables for REPLICATE_API_TOKEN and optionally REPLICATE_MODEL.

API Parameters

| Parameter | Type | Required | Default | Description | |--------------------|---------|----------|---------|------------------------------------------------| | prompt | string | Yes | - | Text prompt for image generation | | output_dir | string | Yes | - | Server directory path to save generated images | | filename | string | No | - | Base name for the output file(s) | | go_fast | boolean | No | false | Enable faster generation mode | | megapixels | string | No | "1" | Resolution quality ("1", "2", "4") | | num_outputs | number | No | 1 | Number of images to generate (1-4) | | aspect_ratio | string | No | "1:1" | Aspect ratio ("1:1", "4:3", "16:9") | | output_format | string | No | "webp" | Image format ("webp", "png", "jpeg") | | output_quality | number | No | 80 | Compression quality (1-100) | | num_inference_steps| number| No | 4 | Number of denoising steps (4-20) |

Example Request

{
  "prompt": "black forest gateau cake spelling out 'FLUX SCHNELL'",
  "output_dir": "/var/output/images",
  "filename": "black_forest_cake",
  "output_format": "webp",
  "go_fast": true,
  "megapixels": "1",
  "num_outputs": 2,
  "aspect_ratio": "1:1"
}

Example Response

{
  "image_paths": [
    "/var/output/images/black_forest_cake_1.webp",
    "/var/output/images/black_forest_cake_2.webp"
  ],
  "metadata": {
    "model": "black-forest-labs/flux-schnell",
    "inference_time_ms": 2847,
    "cache_hit": false
  }
}

Error Handling

The server handles the following error types:

• Validation errors (invalid parameters)
• API errors (Replicate API issues)
• Server errors (filesystem, permissions)
• Unknown errors (unexpected issues)

Each error response includes:

• Error code
• Human-readable message
• Detailed error information

License

ISC