📌Overview

Purpose: To provide a FastMCP server implementation for the Replicate API that enables resource-based access to AI model inference, specifically focused on image generation.

Overview: MCP Server Replicate offers a robust solution for generating and managing images using AI models. It streamlines user interaction with various model parameters, supports real-time updates, and allows for dynamic image generation through natural language processing.

Key Features:

Resource-based image generation and management: Facilitates efficient creation and organization of images derived from user prompts.
Real-time updates through subscriptions: Keeps users informed about the status of their image generation requests.
Template-driven parameter configuration: Simplifies the customization of image generation settings, allowing users to tailor outputs to specific needs.
Webhook integration for external notifications: Enables seamless interaction with external systems by providing notification capabilities.
Quality and style presets: Offers various options for image quality and style, ensuring optimal generation results.
Comprehensive model discovery and selection: Assists users in finding the most suitable AI models for their tasks through an intuitive interface.
Progress tracking and status monitoring: Allows users to monitor the progress of their image generation in real time.
Secure API key management: Ensures safe handling of API keys necessary for interactions with the Replicate platform.

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

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

Implementation Plan
Contributing Guide
API Reference
Resource System
Template System

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.