READMEmain

MCP Server Replicate

A FastMCP server implementation for the Replicate API, providing resource-based access to AI model inference with a focus on image generation.

Features

🖼️ Resource-based image generation and management
🔄 Real-time updates through subscriptions
📝 Template-driven parameter configuration
🔍 Comprehensive model discovery and selection
🪝 Webhook integration for external notifications
🎨 Quality and style presets for optimal results
📊 Progress tracking and status monitoring
🔒 Secure API key management

Available Prompts

The server provides several specialized prompts for different tasks:

Text to Image (Primary)

Our most thoroughly tested and robust prompt. Optimized for generating high-quality images from text descriptions with:

Detailed style control
Quality presets (draft, balanced, quality, extreme)
Size and aspect ratio customization
Progress tracking and real-time updates

Example:

Create a photorealistic mountain landscape at sunset with snow-capped peaks, quality level: quality, style: photorealistic

Other Prompts

Image to Image: Transform existing images (coming soon)
Model Selection: Get help choosing the right model for your task
Parameter Help: Understand and configure model parameters

Prerequisites

Python 3.11 or higher
A Replicate API key (get one at https://replicate.com/account)
UV for dependency management

Installation

Installing via Smithery

To install MCP Server Replicate for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @gerred/mcp-server-replicate --client claude

Installing Manually

You can install the package directly from PyPI:

# Using UV (recommended)
uv pip install mcp-server-replicate

# Using UVX for isolated environments
uvx install mcp-server-replicate

# Using pip
pip install mcp-server-replicate

Claude Desktop Integration

Make sure you have the latest version of Claude Desktop installed
Open your Claude Desktop configuration:

# macOS
code ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
code %APPDATA%\Claude\claude_desktop_config.json

Add the server configuration using one of these options:

{
  "globalShortcut": "Shift+Alt+A",
  "mcpServers": {
    "replicate": {
      "command": "uv",
      "args": ["tool", "run", "mcp-server-replicate"],
      "env": {
        "REPLICATE_API_TOKEN": "APITOKEN"
      },
      "cwd": "$PATH_TO_REPO"
    }
  }
}

Set your Replicate API key:

# Option 1: Set in your environment
export REPLICATE_API_TOKEN=your_api_key_here

# Option 2: Create a .env file in your home directory
echo "REPLICATE_API_TOKEN=your_api_key_here" > ~/.env

Restart Claude Desktop completely

You should now see the 🔨 icon in Claude Desktop, indicating that the MCP server is available.

Usage

Once connected to Claude Desktop, you can:

Generate images with natural language:

Create a photorealistic mountain landscape at sunset with snow-capped peaks

Browse your generations:
```
Show me my recent image generations
```
Search through generations:
```
Find my landscape generations
```

Check generation status:

What's the status of my last generation?

Troubleshooting

Server not showing up in Claude Desktop

Check the Claude Desktop logs:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Verify your configuration:

Make sure the path in claude_desktop_config.json is absolute
Ensure UV is installed and in your PATH
Check that your Replicate API key is set

Try restarting Claude Desktop

For more detailed troubleshooting, see our Debugging Guide.

Documentation

Development

Clone the repository:

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

Install development dependencies:

uv pip install --system ".[dev]"

Install pre-commit hooks:

pre-commit install

Run tests:

pytest

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Replicate