Replicate Flux Image Generation MCP Server

Overview

This MCP (Model Context Protocol) server exposes the Replicate Flux image-generation model as a tool that integrates with MCP-compatible clients (for example Claude Desktop). It lets developers generate high-quality images from text prompts, with configurable aspect ratios, formats, seeds, and batch sizes. The server handles authentication with Replicate and streams requests to the chosen Flux model, returning URLs to the generated assets.

This is useful when you want fast, scalable image generation embedded directly into an assistant or development workflow. Instead of managing model inference locally, the server delegates work to Replicate while presenting a simple MCP tool interface for orchestration and automation.

Repository: https://github.com/GongRzhe/Image-Generation-MCP-Server

Features

• Generate images from text prompts using Replicate Flux models
• Control seed, aspect ratio, output format (webp/jpg/png), and number of outputs
• Defaults tuned for fast generation (default model: black-forest-labs/flux-schnell)
• Simple MCP server that runs via npx or local Node installation
• Integrates with MCP clients (auto-approve configuration supported)
• Returns public URLs for each generated image

Installation / Configuration

Prerequisites: Node.js installed (for local install) and a Replicate API token.

1. Get a Replicate API token:

   • Sign up or log in at https://replicate.com
   • Visit https://replicate.com/account/api-tokens and create a token
   • Store the token for use in MCP configuration (REPLICATE_API_TOKEN)

2. Install or run via npx (no local install required):

Bash (Smithery install example)

npx -y @smithery/cli install @GongRzhe/Image-Generation-MCP-Server --client claude

Run directly from npm (npx)

# Runs the MCP server without installing locally
npx @gongrzhe/image-gen-server

Local installation

# Global
npm install -g @gongrzhe/image-gen-server

# Or local to a project
npm install @gongrzhe/image-gen-server

3. Configure your MCP client (example JSON blocks shown for Claude Desktop).

NPX-based configuration (recommended)

{
  "mcpServers": {
    "image-gen": {
      "command": "npx",
      "args": ["@gongrzhe/image-gen-server"],
      "env": {
        "REPLICATE_API_TOKEN": "your-replicate-api-token",
        "MODEL": "black-forest-labs/flux-schnell"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Local-install configuration

{
  "mcpServers": {
    "image-gen": {
      "command": "node",
      "args": ["/path/to/image-gen-server/build/index.js"],
      "env": {
        "REPLICATE_API_TOKEN": "your-replicate-api-token",
        "MODEL": "black-forest-labs/flux-schnell"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Environment variables

Other configuration flags in the MCP client:

• disabled: true/false — enable or disable the server
• autoApprove: list — tools that can be executed without manual confirmation

Available Tools

generate_image — main tool to produce images from text prompts.

Parameters

Example TypeScript call (using an MCP client helper)

const result = await use_mcp_tool({
  server_name: "image-gen",
  tool_name: "generate_image",
  arguments: {
    prompt: "A futuristic city skyline at dusk, neon lights, cinematic",
    aspect_ratio: "16:9",
    output_format: "png",
    num_outputs: 2
  }
});
console.log(result); // Array of image URLs

Return format: array of public URLs (strings). These point to Replicate-hosted images.

Use Cases

• Rapid prototyping: Quickly generate concept art or UI backgrounds for design review.
• Content creation: Produce social media images or thumbnails with a programmatic workflow.
• Iterative design: Use seed and num_outputs to explore variations from the same prompt.
• Tooling integrations: Embed image generation into chat assistants, bots, or automated pipelines without managing model infrastructure.

Example workflows

• Generate a set of 4 variations for art direction: set num_outputs=4, use a fixed seed for reproducibility.
• Create hero images for blog posts: prompt with theme + color palette, set aspect_ratio to 16:9 and output_format to jpg.

Notes & Troubleshooting

• Generated URLs are hosted by Replicate — they remain valid according to Replicate’s retention policies.
• If you see authentication errors, verify REPLICATE_API_TOKEN and that the token has the required scopes on Replicate.
• To change performance/quality, switch the MODEL env var to another Replicate Flux variant.

License

MIT — see repository for full license details.