FLUX Kontext

This MCP server gives you direct access to FLUX.1 Kontext [Max], a frontier image generation model, through the Replicate API. You can generate high‑quality images, edit images, and manage predictions from your MCP client with reliable error handling and automatic local image download.

How to use

You use this MCP server by connecting your MCP client to one or more configured servers. Start a generation through the client and you will provide a text prompt, optionally an input image, and parameters like aspect ratio, output format, and safety level. The server returns image URLs and local file paths, and it automatically downloads generated images to a local images directory. You can track progress for asynchronous generations, cancel predictions if needed, and retrieve detailed status and results using the provided endpoints.

How to install

Prerequisites: install Node.js 18 or higher and obtain a Replicate API token.

# Prerequisites
node --version
# You should see a version of Node.js 18 or higher

Installation steps

1. Get your Replicate API token by signing up at Replicate, then generate an API token (starts with r8_).

2. Clone the MCP server repository and navigate into it.

git clone https://github.com/PierrunoYT/replicate-flux-kontext-max-mcp-server.git
cd replicate-flux-kontext-max-mcp-server

Run with npx for universal portability

Use a universal npx configuration to run on any machine with Node.js. This pulls the latest version directly from the repository and provides your API token in the environment.

{
  "mcpServers": {
    "replicate-flux-kontext-max": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/PierrunoYT/replicate-flux-kontext-max-mcp-server.git"
      ],
      "env": {
        "REPLICATE_API_TOKEN": "r8_your-replicate-api-token-here"
      }
    }
  }
}

Local installation and configuration for clients

If you prefer running from a local build, you can point your MCP client to the local build file. Add this to your client’s MCP settings (examples shown for common clients):

{
  "mcpServers": {
    "replicate-flux-kontext-max": {
      "command": "node",
      "args": ["path/to/replicate-flux-kontext-max-mcp-server/build/index.js"],
      "env": {
        "REPLICATE_API_TOKEN": "r8_your-replicate-api-token-here"
      }
    }
  }
}

Prediction management and async tracking

You can run synchronous or asynchronous generations. For long or complex prompts, use the async option to start a prediction and then poll its status using the provided prediction ID. You can cancel a running prediction if needed and retrieve detailed results once complete.

Image download and storage behavior

Generated images are automatically downloaded to a local images directory. Filenames are constructed to include the prompt, seed (if provided), an index number, and a timestamp to ensure uniqueness.

Security and reliability notes

The server gracefully handles missing API tokens and other errors without crashing. It performs null-safety checks and includes robust error reporting. Shutdown handlers ensure a clean exit on SIGINT or SIGTERM.

Example usage scenarios

Basic usage: Generate a photorealistic image from a descriptive prompt and let the server download the result locally.

Available tools

flux_kontext_max_generate

Generate images using FLUX.1 Kontext [Max] with real-time processing via Replicate.

flux_kontext_max_generate_async

Generate images with asynchronous prediction tracking and progress updates.

flux_kontext_max_cancel_prediction

Cancel a running prediction by its ID.

flux_kontext_max_get_prediction

Retrieve the status and details of a prediction by ID.