# Replicate Recraft V3 MCP Server
A Model Context Protocol (MCP) server that provides access to the recraft-ai/recraft-v3 image generation model via Replicate. This server allows you to generate high-quality images using advanced AI technology through the Replicate platform.
## Features
- **High-Quality Image Generation**: Generate stunning images using the recraft-ai/recraft-v3 model
- **Multiple Generation Methods**: Support for synchronous and asynchronous generation with prediction tracking
- **Flexible Sizing Options**: Support for various sizes and aspect ratios
- **Advanced Style Control**: Multiple style options including realistic images and digital illustrations
- **Local Image Download**: Automatically downloads generated images to local storage in WebP 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-recraft-v3-mcp-server.git
```
### Option 2: Local Installation
1. Clone this repository:
```bash
git clone https://github.com/PierrunoYT/replicate-recraft-v3-mcp-server.git
cd replicate-recraft-v3-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-recraft-v3": {
"command": "npx",
"args": [
"-y",
"https://github.com/PierrunoYT/replicate-recraft-v3-mcp-server.git"
],
"env": {
"REPLICATE_API_TOKEN": "r8_NBY**********************************"
}
}
}
}
```
#### Local Installation Configuration
For local installations, use:
```json
{
"mcpServers": {
"replicate-recraft-v3": {
"command": "node",
"args": ["/path/to/replicate-recraft-v3-mcp-server/build/index.js"],
"env": {
"REPLICATE_API_TOKEN": "r8_NBY**********************************"
}
}
}
}
```
## Available Tools
### 1. `recraft_v3_generate`
Generate images using the standard synchronous method.
**Parameters:**
- `prompt` (required): Text prompt for image generation
- `size` (optional): Size of the generated image (default: "1024x1024")
- Options: "1024x1024", "1365x1024", "1024x1365", "1536x1024", "1024x1536", "1820x1024", "1024x1820", "1024x2048", "2048x1024", "1434x1024", "1024x1434", "1024x1280", "1280x1024", "1024x1707", "1707x1024"
- `aspect_ratio` (optional): Aspect ratio of the generated image (default: "Not set")
- Options: "Not set", "1:1", "4:3", "3:4", "3:2", "2:3", "16:9", "9:16", "1:2", "2:1", "7:5", "5:7", "4:5", "5:4", "3:5", "5:3"
- `style` (optional): Style of the generated image (default: "any")
- Options: "any", "realistic_image", "digital_illustration", "digital_illustration/pixel_art", "digital_illustration/hand_drawn", "digital_illustration/grain", "digital_illustration/infantile_sketch", "digital_illustration/2d_art_poster", "digital_illustration/handmade_3d", "digital_illustration/hand_drawn_outline", "digital_illustration/engraving_color", "digital_illustration/2d_art_poster_2", "realistic_image/b_and_w", "realistic_image/hard_flash", "realistic_image/hdr", "realistic_image/natural_light", "realistic_image/studio_portrait", "realistic_image/enterprise", "realistic_image/motion_blur"
**Example:**
```json
{
"prompt": "a wildlife photography photo of a red panda using a laptop in a snowy forest",
"size": "1365x1024",
"style": "realistic_image/natural_light"
}
```
### 2. `recraft_v3_generate_async`
Generate images using asynchronous method with prediction tracking.
**Parameters:** Same as `recraft_v3_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. `recraft_v3_get_prediction`
Get the status and results of a prediction created with `recraft_v3_generate_async`.
**Parameters:**
- `prediction_id` (required): The prediction ID from async generation
### 4. `recraft_v3_cancel_prediction`
Cancel a running prediction to prevent unnecessary work and reduce costs.
**Parameters:**
- `prediction_id` (required): The prediction ID to cancel
## Sizes and Aspect Ratios
### Supported Sizes
- `1024x1024` - Square (default)
- `1365x1024`, `1024x1365` - Landscape/Portrait
- `1536x1024`, `1024x1536` - Wide landscape/Portrait
- `1820x1024`, `1024x1820` - Ultra-wide landscape/Portrait
- `1024x2048`, `2048x1024` - Extra tall/wide
- `1434x1024`, `1024x1434` - Custom ratio
- `1024x1280`, `1280x1024` - 4:5 ratio
- `1024x1707`, `1707x1024` - Golden ratio
### Supported Aspect Ratios
- `1:1` - Square
- `4:3`, `3:4` - Standard ratios
- `3:2`, `2:3` - Classic photo ratios
- `16:9`, `9:16` - Widescreen ratios
- `1:2`, `2:1` - Tall/wide ratios
- `7:5`, `5:7` - Custom ratios
- `4:5`, `5:4` - Social media ratios
- `3:5`, `5:3` - Extended ratios
## Style Options
### Realistic Images
- `realistic_image` - General realistic style
- `realistic_image/b_and_w` - Black and white photography
- `realistic_image/hard_flash` - Hard flash photography
- `realistic_image/hdr` - HDR photography
- `realistic_image/natural_light` - Natural lighting
- `realistic_image/studio_portrait` - Studio portrait style
- `realistic_image/enterprise` - Professional/corporate style
- `realistic_image/motion_blur` - Motion blur effects
### Digital Illustrations
- `digital_illustration` - General digital art
- `digital_illustration/pixel_art` - Pixel art style
- `digital_illustration/hand_drawn` - Hand-drawn appearance
- `digital_illustration/grain` - Textured/grainy style
- `digital_illustration/infantile_sketch` - Childlike sketch style
- `digital_illustration/2d_art_poster` - 2D poster art
- `digital_illustration/handmade_3d` - 3D handmade style
- `digital_illustration/hand_drawn_outline` - Outlined hand-drawn style
- `digital_illustration/engraving_color` - Colored engraving style
- `digital_illustration/2d_art_poster_2` - Alternative 2D poster style
## Output
Generated images are automatically downloaded to a local `images/` directory with descriptive filenames in WebP 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 recraft-ai/recraft-v3 API via Replicate. For detailed API documentation, visit:
- [Replicate Recraft V3](https://replicate.com/recraft-ai/recraft-v3)
- [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-recraft-v3-mcp-server/issues)
- Check the [Replicate documentation](https://replicate.com/docs)
## Changelog
### 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
