Replicate MCP Server

A comprehensive MCP (Model Context Protocol) server that enables LLM clients to generate, edit, and evaluate images through the Replicate API.

Features

• Text-to-Image Generation: Generate single or batch images from text prompts
• Image-to-Image Generation: Transform images based on reference images and prompts
• Image Editing: Edit existing images with text-guided modifications
• Creative Prompts: Generate creative image prompts based on style, subject, and mood
• Batch Processing: Process up to 5 images concurrently
• Progress Reporting: Real-time progress updates for long-running operations
• Error Handling: Comprehensive error handling and validation

Installation

1. Clone the repository:

git clone https://github.com/yourusername/replicate-mcp-server.git
cd replicate-mcp-server

2. Install dependencies using uv:

uv sync

3. Set up your environment:

cp .env.example .env
# Edit .env and add your Replicate API token

Configuration

Environment Variables

Create a .env file with:

REPLICATE_API_TOKEN=your-replicate-api-token-here
LOG_LEVEL=INFO
MAX_BATCH_SIZE=5
REQUEST_TIMEOUT=300
ENABLE_DEBUG=false

Claude Desktop Configuration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "replicate-image-server": {
      "command": "uv",
      "args": [
        "run", 
        "python", 
        "/path/to/replicate-mcp-server/src/main.py"
      ],
      "env": {
        "REPLICATE_API_TOKEN": "your-replicate-api-token"
      }
    }
  }
}

Claude Code Configuration

Add to your Claude Code configuration:

{
  "mcpServers": {
    "replicate-image-server": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "/path/to/replicate-mcp-server/src/main.py"
      ],
      "env": {
        "REPLICATE_API_TOKEN": "your-replicate-api-token",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Available Tools

generate_image

Generate a single image from a text prompt.

Parameters:

• prompt (str): Text description of the image to generate
• width (int): Image width in pixels (256-2048, default: 1024)
• height (int): Image height in pixels (256-2048, default: 1024)
• negative_prompt (str, optional): What to avoid in the image
• num_inference_steps (int): Number of denoising steps (1-50, default: 4)
• guidance_scale (float): How closely to follow the prompt (0.0-20.0, default: 0.0)
• seed (int, optional): Random seed for reproducibility
• model_name (str, optional): Specific model to use

generate_image_batch

Generate multiple images concurrently from text prompts.

Parameters:

• prompts (list[str]): List of text descriptions (max 5 prompts)
• Same optional parameters as generate_image

generate_from_reference_image

Generate an image based on a reference image and text prompt.

Parameters:

• image_url (str): URL of the reference image
• prompt (str): Text description for transformation
• strength (float): Transformation strength (0.1-1.0, default: 0.8)
• Other optional parameters similar to generate_image

edit_image

Edit an existing image based on text prompts.

Parameters:

• image_url (str): URL of the image to edit
• prompt (str): Description of desired edits
• mask_url (str, optional): URL of mask image
• strength (float): Edit strength (0.1-1.0, default: 0.7)
• preserve_original (bool): Whether to preserve unmasked areas (default: true)
• model_name (str, optional): Specific model to use

Available Prompts

creative_image_prompt

Generate creative image prompts based on style, subject, and mood.

Parameters:

• style (str): Art style (default: "photorealistic")
  • Options: photorealistic, anime, oil_painting, watercolor, digital_art, impressionist, cyberpunk, minimalist
• subject (str): Subject matter (default: "landscape")
  • Options: landscape, portrait, architecture, nature, abstract, urban, fantasy, still_life
• mood (str): Mood/atmosphere (default: "serene")
  • Options: serene, dramatic, mysterious, joyful, melancholic, energetic, romantic, ethereal

Models

The server uses the following default models:

• Text-to-Image: bytedance/sdxl-lightning-4step
• Image-to-Image: google/nano-banana
• Image Editing: bytedance/seedream-4

Development

Running Tests

uv run pytest

Type Checking

uv run mypy src

Code Formatting

uv run black src
uv run ruff check src

License

MIT

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

Support

For issues and questions, please open an issue on GitHub.