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
- Clone this repository:
git clone https://github.com/PierrunoYT/replicate-minimax-image-01-mcp-server.git
cd replicate-minimax-image-01-mcp-server
- Install dependencies:
npm install
- 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 generationaspect_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 notificationswebhook_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 landscape4:3- Standard landscape3:2- Classic photo landscape2:3- Classic photo portrait3:4- Standard portrait9:16- Vertical/portrait21: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:
License
MIT License - see LICENSE file for details.
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- 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_*tominimax_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