# 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:
```bash
git clone https://github.com/yourusername/replicate-mcp-server.git
cd replicate-mcp-server
```

2. Install dependencies using uv:
```bash
uv sync
```

3. Set up your environment:
```bash
cp .env.example .env
# Edit .env and add your Replicate API token
```

## Configuration

### Environment Variables

Create a `.env` file with:

```env
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:

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

```json
{
  "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
```bash
uv run pytest
```

### Type Checking
```bash
uv run mypy src
```

### Code Formatting
```bash
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.