# 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:
```bash
npx -y https://github.com/PierrunoYT/replicate-minimax-image-01-mcp-server.git
```
### Option 2: Local Installation
1. Clone this repository:
```bash
git clone https://github.com/PierrunoYT/replicate-minimax-image-01-mcp-server.git
cd replicate-minimax-image-01-mcp-server
```
2. Install dependencies:
```bash
npm install
```
3. Build the project:
```bash
npm run build
```
## Configuration
### Environment Variables
Set your Replicate API token as an environment variable:
```bash
export REPLICATE_API_TOKEN="r8_NBY**********************************"
```
You can get your API token from [Replicate](https://replicate.com/).
### MCP Client Configuration
#### Universal npx Configuration (Recommended)
Add this server to your MCP client configuration:
```json
{
"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:
```json
{
"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:**
```json
{
"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
```bash
npm run dev
```
### Testing the Server
```bash
npm test
```
### Getting the Installation Path
```bash
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](https://replicate.com/minimax/image-01)
- [Replicate API Documentation](https://replicate.com/docs)
## License
MIT License - see [LICENSE](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](https://github.com/PierrunoYT/replicate-minimax-image-01-mcp-server/issues)
- Check the [Replicate documentation](https://replicate.com/docs)
## 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
