Replicate Minimax Image-01 MCP Server

A Model Context Protocol (MCP) server that provides access to the minimax/image-01 image generation model via Replicate. This server allows you to generate high-quality images using advanced AI technology through the Replicate platform with the new file-based API.

Features

• High-Quality Image Generation: Generate stunning images using the minimax/image-01 model
• Multiple Generation Methods: Support for synchronous and asynchronous generation with prediction tracking
• Flexible Aspect Ratios: Support for 8 different aspect ratios including square, landscape, portrait, and ultrawide
• Multiple Image Generation: Generate 1-9 images per request
• Prompt Optimization: Built-in prompt optimization for better results
• Subject Reference Support: Optional character reference image (human face) for consistent character generation
• Local Image Download: Automatically downloads generated images to local storage in JPEG format
• Prediction Management: Create, track, and cancel predictions
• Webhook Support: Optional webhook notifications for completed requests

Installation

Option 1: Universal npx Installation (Recommended)

No local installation required! Use npx to run the server directly:

npx -y https://github.com/PierrunoYT/replicate-minimax-image-01-mcp-server.git

Option 2: Local Installation

1. Clone this repository:

git clone https://github.com/PierrunoYT/replicate-minimax-image-01-mcp-server.git
cd replicate-minimax-image-01-mcp-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

Environment Variables

Set your Replicate API token as an environment variable:

export REPLICATE_API_TOKEN="r8_NBY**********************************"

You can get your API token from Replicate.

MCP Client Configuration

Universal npx Configuration (Recommended)

Add this server to your MCP client configuration:

{
  "mcpServers": {
    "replicate-minimax-image-01": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/PierrunoYT/replicate-minimax-image-01-mcp-server.git"
      ],
      "env": {
        "REPLICATE_API_TOKEN": "r8_NBY**********************************"
      }
    }
  }
}

Local Installation Configuration

For local installations, use:

{
  "mcpServers": {
    "replicate-minimax-image-01": {
      "command": "node",
      "args": ["/path/to/replicate-minimax-image-01-mcp-server/build/index.js"],
      "env": {
        "REPLICATE_API_TOKEN": "r8_NBY**********************************"
      }
    }
  }
}

Available Tools

1. minimax_image_01_generate

Generate images using the standard synchronous method.

Parameters:

• prompt (required): Text prompt for image generation
• aspect_ratio (optional): Aspect ratio of the generated image (default: "1:1")
  • Options: "1:1", "16:9", "4:3", "3:2", "2:3", "3:4", "9:16", "21:9"
• number_of_images (optional): Number of images to generate, 1-9 (default: 1)
• prompt_optimizer (optional): Whether to optimize the prompt for better results (default: true)
• subject_reference (optional): URI string for character reference image (human face)

Example:

{
  "prompt": "a wildlife photography photo of a red panda using a laptop in a snowy forest",
  "aspect_ratio": "16:9",
  "number_of_images": 3,
  "prompt_optimizer": true
}

2. minimax_image_01_generate_async

Generate images using asynchronous method with prediction tracking.

Parameters: Same as minimax_image_01_generate plus:

• webhook (optional): URL for webhook notifications
• webhook_events_filter (optional): Events to send to webhook (default: ["completed"])

Returns: A prediction ID for tracking the job

3. minimax_image_01_get_prediction

Get the status and results of a prediction created with minimax_image_01_generate_async.

Parameters:

• prediction_id (required): The prediction ID from async generation

4. minimax_image_01_cancel_prediction

Cancel a running prediction to prevent unnecessary work and reduce costs.

Parameters:

• prediction_id (required): The prediction ID to cancel

Aspect Ratios

The minimax/image-01 model supports the following aspect ratios:

• 1:1 - Square (default)
• 16:9 - Widescreen landscape
• 4:3 - Standard landscape
• 3:2 - Classic photo landscape
• 2:3 - Classic photo portrait
• 3:4 - Standard portrait
• 9:16 - Vertical/portrait
• 21:9 - Ultrawide landscape

Multiple Image Generation

You can generate between 1 and 9 images in a single request by setting the number_of_images parameter. Each image will be saved with a unique filename and index.

Prompt Optimization

The model includes built-in prompt optimization that can enhance your prompts for better results. This is enabled by default but can be disabled by setting prompt_optimizer to false.

Subject Reference

For consistent character generation across multiple images, you can provide a subject_reference URI pointing to a character reference image (human face) that the model will use as a reference for maintaining character consistency.

Output

Generated images are automatically downloaded to a local images/ directory with descriptive filenames in JPEG format. The response includes:

• Local file paths
• Original URLs
• Image filenames
• Generation parameters used
• Prediction IDs for tracking

Error Handling

The server provides detailed error messages for:

• Missing API tokens
• Invalid parameters
• Network issues
• API rate limits
• Generation failures

Development

Running in Development Mode

npm run dev

Testing the Server

npm test

Getting the Installation Path

npm run get-path

API Reference

This server implements the minimax/image-01 API via Replicate. For detailed API documentation, visit:

• Replicate Minimax Image-01
• Replicate API Documentation

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues and questions:

• Open an issue on GitHub
• Check the Replicate documentation

Changelog

v2.0.0

• BREAKING CHANGE: Complete migration from recraft-ai/recraft-v3 to minimax/image-01
• Updated all tool names from recraft_v3_* to minimax_image_01_*
• NEW: Updated to use the new file-based API structure for better performance
• New parameter schema supporting minimax/image-01 features:
  • 8 aspect ratio options (1:1, 16:9, 4:3, 3:2, 2:3, 3:4, 9:16, 21:9)
  • Multiple image generation (1-9 images per request)
  • Built-in prompt optimization
  • Character reference image support for consistent character generation
• Updated filename generation with minimax_image_01 prefix
• Images now saved in JPEG format instead of WebP
• Comprehensive documentation updates
• Maintained all existing architectural patterns and error handling

v1.0.0

• Initial release with recraft-ai/recraft-v3 integration
• Support for synchronous and asynchronous generation
• Prediction tracking and management
• Multiple size and aspect ratio options
• Comprehensive style control options
• Local image download functionality in WebP format
• Comprehensive error handling