Replicate Flux MCP

Genera imágenes y gráficos vectoriales de alta calidad utilizando la API de Replicate.

GitHub
105

Documentación

MseeP.ai Security Assessment Badge

Replicate Flux MCP

English | 中文

MCP Compatible License TypeScript Model Context Protocol

Trust Score smithery badge NPM Downloads Stars

Replicate Flux MCP es un servidor avanzado del Protocolo de Contexto de Modelos (MCP) que permite a los asistentes de IA generar imágenes de alta calidad y gráficos vectoriales. Por defecto utiliza black-forest-labs/flux-schnell para imágenes rasterizadas y recraft-ai/recraft-v3-svg para salida SVG. Puedes sobrescribir los modelos de imagen/SVG seleccionados mediante variables de entorno, y las herramientas de imagen también aceptan una sobrescritura de model_id por llamada desde la lista de permitidos integrada.

📑 Tabla de Contenidos

🚀 Primeros Pasos e Integración

Proceso de Configuración

  1. Obtén un Token de API de Replicate

    • Regístrate en Replicate
    • Crea un token de API en la configuración de tu cuenta

  2. Elige tu Método de Integración

    • Sigue una de las opciones de integración a continuación según tu cliente MCP preferido

  3. Pide a tu Asistente de IA que Genere una Imagen

    • Simplemente pregunta de forma natural: "¿Puedes generar una imagen de un paisaje montañoso sereno al atardecer?"
    • O sé más específico: "Por favor, crea una imagen que muestre una escena montañosa pacífica con un lago que refleje los colores del atardecer en primer plano"

  4. Explora Funciones Avanzadas

    • Prueba diferentes configuraciones de parámetros para obtener resultados personalizados
    • Experimenta con la generación de SVG usando generate_svg
    • Usa las funciones de generación de imágenes por lotes o de variantes

Integración con Cursor

Método 1: Usando mcp.json

  1. Crea o edita el archivo .cursor/mcp.json en el directorio de tu proyecto:
{
  "mcpServers": {
    "replicate-flux-mcp": {
      "command": "env REPLICATE_API_TOKEN=YOUR_TOKEN npx",
      "args": ["-y", "replicate-flux-mcp"]
    }
  }
}
  1. Reemplaza YOUR_TOKEN con tu token real de API de Replicate
  2. Reinicia Cursor para aplicar los cambios

Método 2: Modo Manual

  1. Abre Cursor y ve a Configuración
  2. Navega a la sección "MCP" o "Model Context Protocol"
  3. Haz clic en "Agregar Servidor" o equivalente
  4. Ingresa el siguiente comando en el campo correspondiente:
env REPLICATE_API_TOKEN=YOUR_TOKEN npx -y replicate-flux-mcp
  1. Reemplaza YOUR_TOKEN con tu token real de API de Replicate
  2. Guarda la configuración y reinicia Cursor si es necesario

Integración con Claude Desktop

  1. Crea o edita el archivo mcp.json en tu directorio de configuración:
{
  "mcpServers": {
    "replicate-flux-mcp": {
      "command": "npx",
      "args": ["-y", "replicate-flux-mcp"],
      "env": {
        "REPLICATE_API_TOKEN": "YOUR TOKEN"
      }
    }
  }
}
  1. Reemplaza YOUR_TOKEN con tu token real de API de Replicate
  2. Reinicia Claude Desktop para aplicar los cambios

Integración con Smithery

Este servidor MCP está disponible como servicio alojado en Smithery, lo que te permite usarlo sin configurar tu propio servidor.

  1. Visita Smithery y crea una cuenta si no tienes una
  2. Navega a la página del servidor Replicate Flux MCP
  3. Haz clic en "Agregar al Espacio de Trabajo" para añadir el servidor a tu espacio de trabajo de Smithery
  4. Configura tu cliente MCP (Cursor, Claude Desktop, etc.) para usar la URL de tu espacio de trabajo de Smithery

Para más información sobre el uso de Smithery con tus clientes MCP, visita la documentación de Smithery.

Integración con Glama.ai

Este servidor MCP también está disponible como servicio alojado en Glama.ai, ofreciendo otra opción para usarlo sin configuración local.

  1. Visita Glama.ai y crea una cuenta si no tienes una
  2. Ve a la página del servidor Replicate Flux MCP
  3. Haz clic en "Instalar Servidor" para añadir el servidor a tu espacio de trabajo
  4. Configura tu cliente MCP para usar tu espacio de trabajo de Glama.ai

Para más información, visita la documentación de servidores MCP de Glama.ai.

Integración con Codex

Añade el servidor a ~/.codex/config.toml:

[mcp_servers.replicate]
command = "npx"
args = ["-y", "replicate-flux-mcp"]
env = { REPLICATE_API_TOKEN = "your-replicate-api-token", REPLICATE_IMAGE_MODEL_ID = "your-image-model-id", REPLICATE_SVG_MODEL_ID = "your-svg-model-id" }
startup_timeout_sec = 30_000

Reemplaza los valores de env según sea necesario. Si omites REPLICATE_IMAGE_MODEL_ID / REPLICATE_SVG_MODEL_ID, el servidor usa black-forest-labs/flux-schnell para imágenes y recraft-ai/recraft-v3-svg para SVGs.

Las herramientas seleccionadas validan las sobrescrituras de modelos contra las listas de permitidos integradas:

  • Generación de imágenes: black-forest-labs/flux-schnell, google/imagen-4, black-forest-labs/flux-kontext-pro, ideogram-ai/ideogram-v3-turbo, black-forest-labs/flux-1.1-pro, black-forest-labs/flux-dev
  • Generación de SVG: recraft-ai/recraft-v3-svg
  • Extras heredados de run_model: minimax/video-01, luma/reframe-video, topazlabs/video-upscale, topazlabs/image-upscale, szcho/codeformer, tencentarc/gfpgan

🌟 Características

  • 🖼️ Generación de Imágenes de Alta Calidad — Imágenes rasterizadas Flux Schnell por defecto, con sobrescrituras de modelo de imagen mediante variables de entorno y por herramienta.
  • 🎨 Gráficos Vectoriales — Recraft V3 SVG para logotipos, iconos y diagramas.
  • 📊 Lotes + Variantes — Genera N imágenes a partir de N prompts o N variantes de un solo prompt (basadas en semilla o en modificadores de prompt).
  • 🧩 Modelos Arbitrarios de Replicate — La vía de escape run_replicate_model acepta cualquier referencia owner/name[:version], con introspección get_model_schema para el esquema de entrada OpenAPI. Lista de permitidos opcional mediante REPLICATE_MODEL_ALLOWLIST.
  • 📦 Salida Estructurada — Cada herramienta generate_* devuelve structuredContent legible por máquina junto con contenido legible por humanos, coincidiendo con un outputSchema por herramienta (URL, prompt, formato, relación de aspecto, semilla por variante, etc.).
  • ⏳ Notificaciones de Progreso — La generación por lotes y de variantes emite notifications/progress para clientes que opten por ello mediante progressToken, de modo que las ejecuciones largas no sean una caja negra.
  • 💬 Prompts Seleccionados — 5 plantillas de prompt listas para usar (logo, portrait, svg-icon, product-shot, isometric-diagram) disponibles en la paleta de barras de Claude Desktop y en el menú @ de Cursor.
  • 🏷️ Anotaciones de Herramienta Adecuadas — readOnlyHint / destructiveHint / openWorldHint / idempotentHint configurados correctamente para que los clientes puedan razonar sobre seguridad y coste.
  • 🪵 Registro Estructurado — Los errores del lado del servidor viajan a través de notifications/message en lugar de stderr.
  • 🔌 Compatibilidad Universal con MCP — Protocolo MCP 2025-11-25; funciona con Claude Desktop, Cursor, Cline, Zed y cualquier cliente que cumpla con la especificación.
  • 🔍 Historial de Generación — Explora ejecuciones anteriores a través de los recursos imagelist, svglist y predictionlist.

📚 Documentación

Herramientas Disponibles

generate_image

Genera una imagen basada en un prompt de texto usando el modelo de imagen configurado (solo lista de permitidos).

{
  prompt: string;                // Required: Text description of the image to generate
  model_id?: string;             // Optional: Override image model (allowlist only)
  seed?: number;                 // Optional: Random seed for reproducible generation
  go_fast?: boolean;             // Optional: Run faster predictions with optimized model (default: true)
  megapixels?: "1" | "0.25";     // Optional: Image resolution (default: "1")
  num_outputs?: number;          // Optional: Number of images to generate (1-4) (default: 1)
  aspect_ratio?: string;         // Optional: Aspect ratio (e.g., "16:9", "4:3") (default: "1:1")
  output_format?: string;        // Optional: Output format ("webp", "jpg", "png") (default: "webp")
  output_quality?: number;       // Optional: Image quality (0-100) (default: 80)
  num_inference_steps?: number;  // Optional: Number of denoising steps (1-4) (default: 4)
  disable_safety_checker?: boolean; // Optional: Disable safety filter (default: false)
  support_image_mcp_response_type?: boolean; // Optional: Return embedded image content when supported (default: true)
}

generate_multiple_images

Genera múltiples imágenes basadas en un array de prompts usando el modelo de imagen configurado (solo lista de permitidos).

{
  prompts: string[];             // Required: Array of text descriptions for images to generate (1-10 prompts)
  model_id?: string;             // Optional: Override image model (allowlist only)
  seed?: number;                 // Optional: Random seed for reproducible generation
  go_fast?: boolean;             // Optional: Run faster predictions with optimized model (default: true)
  megapixels?: "1" | "0.25";     // Optional: Image resolution (default: "1")
  aspect_ratio?: string;         // Optional: Aspect ratio (e.g., "16:9", "4:3") (default: "1:1")
  output_format?: string;        // Optional: Output format ("webp", "jpg", "png") (default: "webp")
  output_quality?: number;       // Optional: Image quality (0-100) (default: 80)
  num_inference_steps?: number;  // Optional: Number of denoising steps (1-4) (default: 4)
  disable_safety_checker?: boolean; // Optional: Disable safety filter (default: false)
  support_image_mcp_response_type?: boolean; // Optional: Return embedded image content when supported (default: true)
}

generate_image_variants

Genera múltiples variantes de la misma imagen a partir de un solo prompt usando el modelo de imagen configurado (solo lista de permitidos).

{
  prompt: string;                // Required: Text description for the image to generate variants of
  model_id?: string;             // Optional: Override image model (allowlist only)
  num_variants: number;          // Required: Number of image variants to generate (2-10, default: 4)
  prompt_variations?: string[];  // Optional: List of prompt modifiers to apply to variants (e.g., ["in watercolor style", "in oil painting style"])
  variation_mode?: "append" | "replace"; // Optional: How to apply variations - 'append' adds to base prompt, 'replace' uses variations directly (default: "append")
  seed?: number;                 // Optional: Base random seed. Each variant will use seed+variant_index
  go_fast?: boolean;             // Optional: Run faster predictions with optimized model (default: true)
  megapixels?: "1" | "0.25";     // Optional: Image resolution (default: "1")
  aspect_ratio?: string;         // Optional: Aspect ratio (e.g., "16:9", "4:3") (default: "1:1")
  output_format?: string;        // Optional: Output format ("webp", "jpg", "png") (default: "webp")
  output_quality?: number;       // Optional: Image quality (0-100) (default: 80)
  num_inference_steps?: number;  // Optional: Number of denoising steps (1-4) (default: 4)
  disable_safety_checker?: boolean; // Optional: Disable safety filter (default: false)
  support_image_mcp_response_type?: boolean; // Optional: Return embedded image content when supported (default: true)
}

generate_svg

Genera salida SVG/vectorial basada en un prompt de texto usando el modelo SVG configurado (solo lista de permitidos).

{
  prompt: string;                // Required: Text description of the SVG to generate
  size?: string;                 // Optional: Size of the generated SVG (default: "1024x1024")
  style?: string;                // Optional: Style of the generated image (default: "any")
                                // Options: "any", "engraving", "line_art", "line_circuit", "linocut"
}

prediction_list

Recupera una lista de tus predicciones recientes de Replicate.

{
  limit?: number;  // Optional: Maximum number of predictions to return (1-100) (default: 50)
}

get_prediction

Obtiene información detallada sobre una predicción específica.

{
  predictionId: string;  // Required: ID of the prediction to retrieve
}

run_model

Ejecuta un modelo de Replicate en la lista blanca con una carga útil de entrada sin procesar (útil para modelos de video o restauración).

{
  model_id: string;                // Required: Replicate model id (allowlist only)
  input?: Record<string, unknown>; // Optional: Raw input payload for the model
}

run_replicate_model

Ejecuta cualquier modelo alojado en Replicate mediante su referencia owner/name[:version]. Úsalo como vía de escape cuando ninguna de las herramientas seleccionadas se ajuste. Llama a get_model_schema primero si no conoces la forma de la entrada.

{
  model: string;                              // Required: 'owner/name' or 'owner/name:version'
  input: Record<string, unknown>;             // Required: Model input parameters
  prefer_wait?: number;                       // Optional: Seconds to block waiting for sync output (1-60, default 60)
  return_as?: "url" | "base64" | "both";      // Optional: How to return file outputs (default "url")
}

Configura la variable de entorno REPLICATE_MODEL_ALLOWLIST (entradas owner/name separadas por comas) para restringir qué modelos pueden invocarse. Sin configurar = cualquier modelo permitido. Configurada pero vacía = denegar todo (el servidor falla de forma segura en lugar de permitir silenciosamente todo).

get_model_schema

Obtiene el esquema de entrada OpenAPI y la descripción de un modelo de Replicate para que puedas pasar los parámetros correctos a run_replicate_model.

{
  model: string;  // Required: Replicate model reference in 'owner/name' form
}

Recursos Disponibles

imagelist

Explora tu historial de imágenes generadas creadas con el modelo de imagen configurado.

svglist

Explora tu historial de salidas SVG generadas con el modelo SVG configurado.

predictionlist

Explora todo tu historial de predicciones de Replicate.

Prompts Disponibles

Plantillas seleccionadas disponibles en el menú de barras de Claude Desktop y en la paleta @ de Cursor. Cada una completa valores predeterminados sensatos y luego delega en la herramienta de generación correspondiente.

PromptDescripciónArgumentos
logoLogotipo de marca/productobrand, style?, palette?
portraitRetrato fotorrealistasubject, mood?, lens?
svg-iconIcono vectorial de concepto únicoconcept, style?
product-shotFotografía de producto de estudioproduct, surface?
isometric-diagramIlustración técnica isométricasubject, emphasis?

Salida Estructurada

Cada herramienta generate_* devuelve tanto content legible por humanos (bloques de texto e imagen) como structuredContent legible por máquina que coincide con el outputSchema de la herramienta.

HerramientaForma de structuredContent
generate_image{ url, prompt, format, aspect_ratio, seed? }
generate_svg{ url, prompt, size, style, svg? }
generate_multiple_images{ images: [{ url, prompt }], format, aspect_ratio }
generate_image_variants{ base_prompt, variation_mode, variants: [{ variant_index, url, prompt_used, seed? }], format, aspect_ratio }

Los clientes que entienden la salida estructurada de MCP pueden consumir URLs y metadatos directamente sin analizar texto.

Variables de Entorno

VariableRequeridaPropósito
REPLICATE_API_TOKENsíToken de API para Replicate. El servidor se cierra inmediatamente si falta.
REPLICATE_IMAGE_MODEL_IDnoSobrescribe el modelo de imagen seleccionado por defecto usado por generate_image, generate_multiple_images, generate_image_variants y create_prediction. El valor debe estar en la lista de permitidos de imágenes integrada.
REPLICATE_SVG_MODEL_IDnoSobrescribe el modelo SVG por defecto usado por generate_svg. El valor debe estar en la lista de permitidos de SVG integrada.
REPLICATE_MODEL_ALLOWLISTnoEntradas owner/name separadas por comas que controlan run_replicate_model. Sin configurar = cualquier modelo permitido. Configurada pero vacía = denegar todo (fallo seguro). Se evalúa una vez al inicio del proceso, así que configúrala en el bloque env de tu cliente MCP (no mediante un dotenv cargado más tarde).

💻 Desarrollo

  1. Clona el repositorio:
git clone https://github.com/awkoy/replicate-flux-mcp.git
cd replicate-flux-mcp
  1. Instala las dependencias:
npm install
  1. Inicia el observador de TypeScript:
npm run watch
  1. Compila el proyecto:
npm run build
  1. Prueba el servidor con el MCP Inspector:
npm run inspector
  1. Conéctate al Cliente:
{
  "mcpServers": {
    "image-generation-mcp": {
      "command": "npx",
      "args": [
        "/Users/{USERNAME}/{PATH_TO}/replicate-flux-mcp/build/index.js"
      ],
      "env": {
        "REPLICATE_API_TOKEN": "YOUR REPLICATE API TOKEN"
      }
    }
  }
}

Pruebas

Este proyecto actualmente no tiene un conjunto de pruebas automatizadas. La verificación se realiza mediante:

  • npm run build — La verificación de tipos de TypeScript detecta la mayoría de las regresiones.
  • npm run inspector — Ejecuta el binario compilado a través del MCP Inspector oficial para pruebas de humo de extremo a extremo de herramientas, recursos y prompts.

Se agradecen contribuciones que añadan un marco de pruebas adecuado (por ejemplo, Vitest + un cliente stdio de MCP).

⚙️ Detalles Técnicos

Stack

  • Model Context Protocol SDK - Funcionalidad central de MCP para la gestión de herramientas y recursos
  • Replicate API - Proporciona acceso a modelos de generación de imágenes con IA de última generación
  • TypeScript - Garantiza la seguridad de tipos y aprovecha las características modernas de JavaScript
  • Zod - Implementa la validación de tipos en tiempo de ejecución para interacciones robustas con la API

Configuración

El servidor se puede configurar modificando el objeto CONFIG en src/config/index.ts o estableciendo las variables de entorno REPLICATE_IMAGE_MODEL_ID / REPLICATE_SVG_MODEL_ID para sobrescribir los valores predeterminados:

export const CONFIG = {
  serverName: "replicate-flux-mcp",
  serverVersion: "0.4.0",
  imageModelId: process.env.REPLICATE_IMAGE_MODEL_ID ?? "black-forest-labs/flux-schnell",
  svgModelId: process.env.REPLICATE_SVG_MODEL_ID ?? "recraft-ai/recraft-v3-svg",
  pollingAttempts: 25,
  pollingInterval: 2000, // ms
  modelAllowlistConfigured: process.env.REPLICATE_MODEL_ALLOWLIST !== undefined,
  modelAllowlist: (process.env.REPLICATE_MODEL_ALLOWLIST ?? "")
    .split(",")
    .map((s) => s.trim())
    .filter(Boolean),
};

Cambio de modelos (sin cambios de código)

Usa variables de entorno al iniciar el servidor (funciona con npx, Cursor, Claude Desktop, etc.). Las anulaciones de herramientas de imagen/SVG seleccionadas deben estar en las listas de permitidos integradas:

# Stay on defaults:
REPLICATE_API_TOKEN=YOUR_TOKEN npx -y replicate-flux-mcp

# Switch to other allowlisted models
REPLICATE_IMAGE_MODEL_ID="google/imagen-4" \
REPLICATE_SVG_MODEL_ID="recraft-ai/recraft-v3-svg" \
REPLICATE_API_TOKEN=YOUR_TOKEN \
npx -y replicate-flux-mcp

modelAllowlist se evalúa una vez al inicio del proceso desde REPLICATE_MODEL_ALLOWLIST. Reinicia el servidor después de cambiarlo.

🔍 Solución de problemas

Problemas comunes

Error de autenticación

  • Asegúrate de que tu REPLICATE_API_TOKEN esté configurada correctamente en el entorno
  • Verifica que tu token sea válido probándolo directamente con la API de Replicate

Filtro de seguridad activado

  • El modelo tiene un filtro de seguridad integrado que puede bloquear ciertos mensajes
  • Intenta modificar tu mensaje para evitar contenido potencialmente problemático

Error de tiempo de espera

  • Para imágenes más grandes o servidores ocupados, es posible que necesites aumentar pollingAttempts o pollingInterval en la configuración
  • La configuración predeterminada debería funcionar para la mayoría de los casos de uso

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Sigue estos pasos para contribuir:

  1. Haz un fork del repositorio
  2. Crea tu rama de características (git checkout -b feature/amazing-feature)
  3. Realiza tus cambios (git commit -m 'Add some amazing feature')
  4. Envía los cambios a la rama (git push origin feature/amazing-feature)
  5. Abre una solicitud de extracción

Para solicitudes de funciones o informes de errores, crea un problema en GitHub. Si te gusta este proyecto, ¡considera darle una estrella al repositorio!

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT: consulta el archivo LICENSE para más detalles.

🔗 Recursos

🎨 Ejemplos

Demo

Múltiples mensajesVariantes de mensajes
Multiple prompts example: "A serene mountain lake at sunset", "A bustling city street at night", "A peaceful garden in spring"Variants example: Base prompt "A majestic castle" with modifiers "in watercolor style", "as an oil painting", "with gothic architecture"

Aquí hay algunos ejemplos de cómo usar las herramientas:

Generación de imágenes por lotes con generate_multiple_images

Crea múltiples imágenes distintas a la vez con diferentes mensajes:

{
  "prompts": [
    "A red sports car on a mountain road", 
    "A blue sports car on a beach", 
    "A vintage sports car in a city street"
  ]
}

Variantes de imágenes con generate_image_variants

Crea diferentes interpretaciones del mismo concepto usando semillas:

{
  "prompt": "A futuristic city skyline at night",
  "num_variants": 4,
  "seed": 42
}

O explora variaciones de estilo con modificadores de mensajes:

{
  "prompt": "A character portrait",
  "prompt_variations": [
    "in anime style", 
    "in watercolor style", 
    "in oil painting style", 
    "as a 3D render"
  ]
}

Hecho con ❤️ por Yaroslav Boiko