Replicate MCP Server: Model Search, Predictions, Images

Overview

Replicate MCP Server is a lightweight Model Context Protocol (MCP) adapter that exposes Replicate models and predictions through a simple tool-oriented interface. It lets developer agents and tool consumers search available models, start and monitor predictions, and manage generated media (images) in a consistent, programmatic way. The server acts as a bridge between an MCP-enabled orchestrator (or any HTTP client) and the Replicate API, capturing prediction metadata and media artifacts for later inspection and reuse.

This project is useful when you want to integrate image-generation or other model capabilities from Replicate into multi-tool workflows, agents, or production pipelines without embedding Replicate calls directly into your codebase. By centralizing model discovery, prediction execution, status tracking, and media storage, the server simplifies orchestration, debugging, and auditing of model-driven tasks.

Features

• Search and browse Replicate models by name, tag, or description.
• Run predictions on selected models with arbitrary input payloads.
• Track prediction status, outputs, and logs via unique prediction IDs.
• Persist and serve generated images and other media artifacts.
• Simple MCP-compatible tool interface for agent integration.
• Optional local storage for media with API endpoints for listing and downloading.
• Lightweight, container-friendly deployment (Docker/standalone).

Installation / Configuration

Prerequisites:

• Python 3.10+ (if running locally) or Docker
• A Replicate API token (set as environment variable)

Clone and install (local / development):

git clone https://github.com/deepfates/mcp-replicate.git
cd mcp-replicate
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn mcp_replicate.main:app --host 0.0.0.0 --port 8080

Environment variables (example .env):

REPLICATE_API_TOKEN=your_replicate_token_here
MCP_BIND_ADDRESS=0.0.0.0
MCP_PORT=8080
MEDIA_STORAGE_PATH=./media      # where generated images are saved
DB_URL=sqlite:///./mcp.db       # optional persistence
SERVER_API_KEY=optional_server_api_key

Run with Docker:

docker build -t mcp-replicate .
docker run -e REPLICATE_API_TOKEN="$REPLICATE_API_TOKEN" \
           -e MCP_PORT=8080 \
           -p 8080:8080 \
           -v $(pwd)/media:/app/media \
           mcp-replicate

Or use docker-compose (example):

version: "3.8"
services:
  mcp-replicate:
    image: deepfates/mcp-replicate:latest
    environment:
      - REPLICATE_API_TOKEN=${REPLICATE_API_TOKEN}
      - MCP_PORT=8080
    ports:
      - "8080:8080"
    volumes:
      - ./media:/app/media

Available Tools / Resources

The server exposes a set of MCP-style tools and HTTP endpoints to interact with Replicate resources. Names are illustrative; check the running server’s /tools endpoint for exact identifiers.

Tool summary:

• replicate_search — Find models by query, tag, or author.
• replicate_list_models — Browse models with pagination.
• replicate_predict — Start a prediction on a model with inputs.
• replicate_get_prediction — Retrieve prediction state and outputs.
• replicate_list_predictions — List stored predictions for auditing.
• replicate_list_images — List generated images and metadata.
• replicate_get_image — Download a specific media artifact.

HTTP endpoint examples (common paths):

Use Cases

1. Search for a model by keyword

• Request (curl):

curl -X POST http://localhost:8080/models/search \
  -H "Content-Type: application/json" \
  -d '{"query":"stable diffusion","limit":5}'

• Response: JSON list of matching models with metadata and version IDs.

2. Run an image generation prediction and track it

• Start prediction:

curl -X POST http://localhost:8080/predictions \
  -H "Content-Type: application/json" \
  -d '{
    "model":"stability-ai/stable-diffusion",
    "version":"<model-version-id>",
    "input": {"prompt":"a scenic mountain landscape, high detail"}
  }'

• Get status and outputs:

curl http://localhost:8080/predictions/<prediction-id>

When the prediction completes, the server will persist any image outputs in MEDIA_STORAGE_PATH and include file URLs in the prediction metadata.

3. Integrating with an MCP-enabled agent

• The server advertises MCP tools (e.g., replicate_predict) so an agent can call those tools using the MCP protocol rather than handling raw Replicate credentials. This keeps the agent workflow decoupled from API specifics and centralizes model access control.

4. Audit and replay

• Use /predictions to list historical runs and inspect inputs, status, logs, and produced media. Download stored images for review, reuse, or embedding in reports.

Tips and Notes

• Keep your Replicate API token secret. The server reads it from REPLICATE_API_TOKEN on startup.
• Configure MEDIA_STORAGE_PATH to a persistent volume in production, or integrate object storage if needed.
• For heavy traffic, run multiple instances behind a load balancer and use a central database (DB_URL) to share prediction metadata.