Replicate Flux MCP

Gere imagens de alta qualidade e gráficos vetoriais usando a API do Replicate.

GitHub
106
Experimente este MCPPatrocinado

Documentação

MseeP.ai Security Assessment Badge

Replicate Flux MCP

English | 中文

MCP Compatible License TypeScript Model Context Protocol

Trust Score LightNow NPM Downloads Stars

Replicate Flux MCP é um servidor avançado do Model Context Protocol (MCP) que capacita assistentes de IA a gerar imagens de alta qualidade e gráficos vetoriais. Por padrão, ele usa black-forest-labs/flux-schnell para imagens raster e recraft-ai/recraft-v3-svg para saída SVG. Você pode substituir os modelos de imagem/SVG selecionados por meio de variáveis de ambiente, e as ferramentas de imagem também aceitam uma substituição de model_id por chamada a partir da lista de permissões integrada.

📑 Sumário

🚀 Introdução e Integração

Processo de Configuração

  1. Obtenha um Token de API do Replicate

    • Cadastre-se em Replicate
    • Crie um token de API nas configurações da sua conta

  2. Escolha Seu Método de Integração

    • Siga uma das opções de integração abaixo com base no seu cliente MCP preferido

  3. Peça ao Seu Assistente de IA para Gerar uma Imagem

    • Simplesmente pergunte naturalmente: "Você pode gerar uma imagem de uma paisagem montanhosa serena ao pôr do sol?"
    • Ou seja mais específico: "Por favor, crie uma imagem mostrando uma cena montanhosa pacífica com um lago refletindo as cores do pôr do sol em primeiro plano"

  4. Explore Recursos Avançados

    • Experimente diferentes configurações de parâmetros para resultados personalizados
    • Experimente a geração de SVG usando generate_svg
    • Use os recursos de geração de imagens em lote ou de geração de variantes

Integração com Cursor

Método 1: Usando mcp.json

  1. Crie ou edite o arquivo .cursor/mcp.json no diretório do seu projeto:
{
  "mcpServers": {
    "replicate-flux-mcp": {
      "command": "env REPLICATE_API_TOKEN=YOUR_TOKEN npx",
      "args": ["-y", "replicate-flux-mcp"]
    }
  }
}
  1. Substitua YOUR_TOKEN pelo seu token de API real do Replicate
  2. Reinicie o Cursor para aplicar as alterações

Método 2: Modo Manual

  1. Abra o Cursor e vá para Configurações
  2. Navegue até a seção "MCP" ou "Model Context Protocol"
  3. Clique em "Adicionar Servidor" ou equivalente
  4. Insira o seguinte comando no campo apropriado:
env REPLICATE_API_TOKEN=YOUR_TOKEN npx -y replicate-flux-mcp
  1. Substitua YOUR_TOKEN pelo seu token de API real do Replicate
  2. Salve as configurações e reinicie o Cursor se necessário

Integração com Claude Desktop

  1. Crie ou edite o arquivo mcp.json no seu diretório de configuração:
{
  "mcpServers": {
    "replicate-flux-mcp": {
      "command": "npx",
      "args": ["-y", "replicate-flux-mcp"],
      "env": {
        "REPLICATE_API_TOKEN": "YOUR TOKEN"
      }
    }
  }
}
  1. Substitua YOUR_TOKEN pelo seu token de API real do Replicate
  2. Reinicie o Claude Desktop para aplicar as alterações

Integração com Smithery

Este servidor MCP está disponível como um serviço hospedado no Smithery, permitindo que você o use sem configurar seu próprio servidor.

  1. Visite Smithery e crie uma conta se você não tiver uma
  2. Navegue até a página do servidor Replicate Flux MCP
  3. Clique em "Adicionar ao Workspace" para adicionar o servidor ao seu workspace do Smithery
  4. Configure seu cliente MCP (Cursor, Claude Desktop, etc.) para usar a URL do seu workspace do Smithery

Para mais informações sobre como usar o Smithery com seus clientes MCP, visite a documentação do Smithery.

Integração com Glama.ai

Este servidor MCP também está disponível como um serviço hospedado no Glama.ai, fornecendo outra opção para usá-lo sem configuração local.

  1. Visite Glama.ai e crie uma conta se você não tiver uma
  2. Vá para a página do servidor Replicate Flux MCP
  3. Clique em "Instalar Servidor" para adicionar o servidor ao seu workspace
  4. Configure seu cliente MCP para usar seu workspace do Glama.ai

Para mais informações, visite a documentação de servidores MCP do Glama.ai.

Integração com Codex

Adicione o servidor ao ~/.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

Substitua os valores de env conforme necessário. Se você omitir REPLICATE_IMAGE_MODEL_ID / REPLICATE_SVG_MODEL_ID, o servidor usa black-forest-labs/flux-schnell para imagens e recraft-ai/recraft-v3-svg para SVGs.

As ferramentas selecionadas validam substituições de modelo contra listas de permissões integradas:

  • Geração de imagens: 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
  • Geração de SVG: recraft-ai/recraft-v3-svg
  • Extras legados de run_model: minimax/video-01, luma/reframe-video, topazlabs/video-upscale, topazlabs/image-upscale, szcho/codeformer, tencentarc/gfpgan

🌟 Recursos

  • 🖼️ Geração de Imagens de Alta Qualidade — Imagens raster Flux Schnell por padrão, com substituições de modelo de imagem por variável de ambiente e por ferramenta.
  • 🎨 Gráficos Vetoriais — Recraft V3 SVG para logotipos, ícones e diagramas.
  • 📊 Lote + Variantes — Gere N imagens a partir de N prompts ou N variantes de um único prompt (baseado em seed ou em modificador de prompt).
  • 🧩 Modelos Replicate Arbitrários — A saída de escape run_replicate_model aceita qualquer referência owner/name[:version], com introspecção get_model_schema para o esquema de entrada OpenAPI. Lista de permissões opcional via REPLICATE_MODEL_ALLOWLIST.
  • 📦 Saída Estruturada — Cada ferramenta generate_* retorna structuredContent legível por máquina junto com conteúdo legível por humanos, correspondendo a um outputSchema por ferramenta (URL, prompt, formato, proporção de aspecto, seed por variante, etc).
  • ⏳ Notificações de Progresso — A geração em lote e de variantes emite notifications/progress para clientes que optam por participar via progressToken, para que execuções longas não sejam caixas-pretas.
  • 💬 Prompts Selecionados — 5 modelos de prompt prontos (logo, portrait, svg-icon, product-shot, isometric-diagram) exibidos na paleta de barra do Claude Desktop e no menu @ do Cursor.
  • 🏷️ Anotações de Ferramenta Adequadas — readOnlyHint / destructiveHint / openWorldHint / idempotentHint definidos corretamente para que os clientes possam raciocinar sobre segurança e custo.
  • 🪵 Registro Estruturado — Erros do lado do servidor viajam por notifications/message em vez de stderr.
  • 🔌 Compatibilidade Universal com MCP — Protocolo MCP 2025-11-25; funciona com Claude Desktop, Cursor, Cline, Zed e qualquer cliente compatível com a especificação.
  • 🔍 Histórico de Geração — Navegue por execuções passadas por meio dos recursos imagelist, svglist e predictionlist.

📚 Documentação

Ferramentas Disponíveis

generate_image

Gera uma imagem com base em um prompt de texto usando o modelo de imagem configurado (somente lista de permissões).

{
  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

Gera múltiplas imagens com base em uma matriz de prompts usando o modelo de imagem configurado (somente lista de permissões).

{
  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

Gera múltiplas variantes da mesma imagem a partir de um único prompt usando o modelo de imagem configurado (somente lista de permissões).

{
  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

Gera saída SVG/vetorial com base em um prompt de texto usando o modelo SVG configurado (somente lista de permissões).

{
  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 uma lista de suas previsões recentes do Replicate.

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

get_prediction

Obtém informações detalhadas sobre uma previsão específica.

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

run_model

Executa um modelo Replicate na lista de permissões com um payload de entrada bruto (útil para modelos de vídeo ou restauração).

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

run_replicate_model

Executa qualquer modelo hospedado no Replicate por sua referência owner/name[:version]. Use isso como uma saída de escape quando nenhuma das ferramentas selecionadas se adequar. Chame get_model_schema primeiro se você não souber a forma da 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")
}

Defina a variável de ambiente REPLICATE_MODEL_ALLOWLIST (entradas owner/name separadas por vírgula) para restringir quais modelos podem ser invocados. Não definido = qualquer modelo permitido. Definido-mas-vazio = negar todos (o servidor falha fechado em vez de permitir silenciosamente tudo).

get_model_schema

Busca o esquema de entrada OpenAPI e a descrição de um modelo Replicate para que você possa passar os parâmetros corretos para run_replicate_model.

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

Recursos Disponíveis

imagelist

Navegue pelo seu histórico de imagens geradas criadas com o modelo de imagem configurado.

svglist

Navegue pelo seu histórico de saídas SVG geradas criadas com o modelo SVG configurado.

predictionlist

Navegue por todo o seu histórico de previsões do Replicate.

Prompts Disponíveis

Modelos selecionados exibidos no menu de barra do Claude Desktop e na paleta @ do Cursor. Cada um preenche padrões sensatos e depois delega para a ferramenta de geração relevante.

PromptDescriçãoArgumentos
logoLogotipo de marca/produtobrand, style?, palette?
portraitRetrato fotorrealistasubject, mood?, lens?
svg-iconÍcone vetorial de conceito únicoconcept, style?
product-shotFotografia de produto em estúdioproduct, surface?
isometric-diagramIlustração técnica isométricasubject, emphasis?

Saída Estruturada

Cada ferramenta generate_* retorna tanto content legível por humanos (blocos de texto + imagem) quanto structuredContent legível por máquina que corresponde ao outputSchema da ferramenta.

FerramentaForma 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 }

Clientes que entendem saída estruturada do MCP podem consumir URLs e metadados diretamente sem analisar prosa.

Variáveis de Ambiente

VariávelObrigatóriaPropósito
REPLICATE_API_TOKENsimToken de API para Replicate. O servidor sai imediatamente se estiver ausente.
REPLICATE_IMAGE_MODEL_IDnãoSubstitui o modelo de imagem selecionado padrão usado por generate_image, generate_multiple_images, generate_image_variants e create_prediction. O valor deve estar na lista de permissões de imagem integrada.
REPLICATE_SVG_MODEL_IDnãoSubstitui o modelo SVG padrão usado por generate_svg. O valor deve estar na lista de permissões SVG integrada.
REPLICATE_MODEL_ALLOWLISTnãoEntradas owner/name separadas por vírgula que controlam run_replicate_model. Não definido = qualquer modelo permitido. Definido-mas-vazio = negar todos (falha fechada). Avaliado uma vez no início do processo, então defina-o no bloco env do seu cliente MCP (não via dotenv carregado posteriormente).

💻 Desenvolvimento

  1. Clone o repositório:
git clone https://github.com/awkoy/replicate-flux-mcp.git
cd replicate-flux-mcp
  1. Instale as dependências:
npm install
  1. Inicie o observador TypeScript:
npm run watch
  1. Compile o projeto:
npm run build
  1. Teste o servidor com o MCP Inspector:
npm run inspector
  1. Conecte-se ao 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"
      }
    }
  }
}

Testes

Este projeto atualmente não possui suíte de testes automatizados. A verificação é feita via:

  • npm run build — A verificação de tipos do TypeScript detecta a maioria das regressões.
  • npm run inspector — Executa o binário compilado através do MCP Inspector oficial para testes de fumaça de ponta a ponta de ferramentas, recursos e prompts.

Contribuições que adicionam uma estrutura de testes adequada (por exemplo, Vitest + um harness de cliente stdio MCP) são bem-vindas.

⚙️ Detalhes Técnicos

Pilha Tecnológica

  • Model Context Protocol SDK - Funcionalidade central do MCP para gerenciamento de ferramentas e recursos
  • Replicate API - Fornece acesso a modelos de geração de imagens por IA de última geração
  • TypeScript - Garante segurança de tipos e aproveita recursos modernos do JavaScript
  • Zod - Implementa validação de tipos em tempo de execução para interações robustas com a API

Configuração

O servidor pode ser configurado modificando o objeto CONFIG em src/config/index.ts ou definindo as variáveis de ambiente REPLICATE_IMAGE_MODEL_ID / REPLICATE_SVG_MODEL_ID para substituir os padrões:

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),
};

Alternando modelos (sem alterações de código)

Use variáveis de ambiente ao iniciar o servidor (funciona com npx, Cursor, Claude Desktop, etc.). As substituições de ferramentas de imagem/SVG selecionadas devem estar nas listas de permissões 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 é avaliado uma vez no início do processo a partir de REPLICATE_MODEL_ALLOWLIST. Reinicie o servidor após alterá-lo.

🔍 Solução de Problemas

Problemas Comuns

Erro de Autenticação

  • Certifique-se de que seu REPLICATE_API_TOKEN esteja configurado corretamente no ambiente
  • Verifique se seu token é válido testando-o diretamente com a API do Replicate

Filtro de Segurança Acionado

  • O modelo possui um filtro de segurança integrado que pode bloquear certos prompts
  • Tente modificar seu prompt para evitar conteúdo potencialmente problemático

Erro de Tempo Limite

  • Para imagens maiores ou servidores ocupados, talvez seja necessário aumentar pollingAttempts ou pollingInterval na configuração
  • As configurações padrão devem funcionar para a maioria dos casos de uso

🤝 Contribuindo

Contribuições são bem-vindas! Siga estes passos para contribuir:

  1. Faça um fork do repositório
  2. Crie sua branch de funcionalidade (git checkout -b feature/amazing-feature)
  3. Faça commit das suas alterações (git commit -m 'Add some amazing feature')
  4. Envie para a branch (git push origin feature/amazing-feature)
  5. Abra um Pull Request

Para solicitações de funcionalidades ou relatórios de bugs, crie uma issue no GitHub. Se você gosta deste projeto, considere dar uma estrela no repositório!

📄 Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

🔗 Recursos

🎨 Exemplos

Demo

Múltiplos PromptsVariantes de Prompt
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"

Aqui estão alguns exemplos de como usar as ferramentas:

Geração de Imagens em Lote com generate_multiple_images

Crie múltiplas imagens distintas de uma vez com prompts diferentes:

{
  "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 Imagem com generate_image_variants

Crie diferentes interpretações do mesmo conceito usando sementes:

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

Ou explore variações de estilo com modificadores de prompt:

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

Feito com ❤️ por Yaroslav Boiko