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:

npx -y https://github.com/PierrunoYT/replicate-recraft-v3-mcp-server.git

Option 2: Local Installation

1. Clone this repository:

git clone https://github.com/PierrunoYT/replicate-recraft-v3-mcp-server.git
cd replicate-recraft-v3-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-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:

{
  "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:

{
  "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

npm run dev

Testing the Server

npm test

Getting the Installation Path

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
• 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

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