FLUX MCP Server

MCP server exposing Replicate's FLUX image generation models to Claude Desktop, Claude Code, and other MCP clients.

Features

• 6 FLUX models via Replicate API:

  • FLUX1.1 Pro Ultra — highest quality text-to-image (up to ~4MP, raw realism mode)
  • FLUX1.1 Pro — fast, reliable commercial-grade default
  • FLUX.1 Redux [dev] — image variations/restyling
  • FLUX.1 Fill [pro] — professional inpainting/outpainting
  • FLUX.1 Depth [dev] — structure-preserving depth-guided editing
  • FLUX.1 Canny [pro] — edge-guided generation from sketches

• Two MCP tools:

  1. flux_models — list models with usage notes
  2. flux_generate — generate images, save locally, return file paths + URLs

Prerequisites

• Replicate API token (required)
• Node.js 18+ (for local development)

Quick Start

Claude Code

From local directory:

cd /path/to/flux-mcp-node
claude mcp add --scope user flux-mcp --env REPLICATE_API_TOKEN=r8_your_token_here -- node /absolute/path/to/flux-mcp-node/index.js

From npm (after publishing):

claude mcp add --scope user flux-mcp --env REPLICATE_API_TOKEN=r8_your_token_here -- npx flux-mcp@latest

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "flux-mcp": {
      "command": "npx",
      "args": ["flux-mcp@latest"],
      "env": {
        "REPLICATE_API_TOKEN": "r8_your_token_here"
      }
    }
  }
}

For local development:

{
  "mcpServers": {
    "flux-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/flux-mcp-node/index.js"],
      "env": {
        "REPLICATE_API_TOKEN": "r8_your_token_here"
      }
    }
  }
}

Restart Claude Desktop. Get your Replicate API token from replicate.com/account/api-tokens.

Local Development

git clone https://github.com/kmaurinjones/flux-mcp.git
cd flux-mcp
npm install
export REPLICATE_API_TOKEN="r8_..."
node index.js

Installation

From npm (after publishing)

npm install -g flux-mcp

From source

git clone https://github.com/kmaurinjones/flux-mcp.git
cd flux-mcp
npm install
npm link

Usage

List available models

Call flux_models() to see all supported models with usage notes.

Returns:

[
  {
    "model": "black-forest-labs/flux-1.1-pro-ultra",
    "display": "FLUX1.1 Pro Ultra",
    "kind": "text-to-image",
    "accepts_image": false,
    "notes": [
      "Highest quality, up to ~4MP; 'raw' mode for realism.",
      "Use when you need best composition/large output."
    ],
    "key_inputs": ["prompt", "raw", "aspect_ratio", "seed", "output_quality", "go_fast"]
  }
]

Generate images

Text-to-image (Pro)

Generate a mountain landscape (PNG by default):
- prompt: "peaceful mountain landscape with snow-capped peaks and evergreen trees, golden hour"
- download_path: "~/Pictures/flux-gen"
- model: "black-forest-labs/flux-pro"
- aspect_ratio: "16:9"

Or specify a different format:

Generate as JPEG:
- prompt: "peaceful mountain landscape with snow-capped peaks and evergreen trees, golden hour"
- download_path: "~/Pictures/flux-gen"
- model: "black-forest-labs/flux-pro"
- aspect_ratio: "16:9"
- output_format: "jpeg"

Text-to-image (Ultra - highest quality)

Generate with maximum quality:
- prompt: "sunlit minimalist living room, soft cream walls, terracotta accents"
- download_path: "~/Pictures/flux-gen"
- model: "black-forest-labs/flux-1.1-pro-ultra"
- aspect_ratio: "16:9"
- raw: true

Image variation (Redux)

Create variations of reference.png:
- prompt: "keep composition, shift to sage/cream palette, add subtle grain"
- download_path: "~/Pictures/flux-gen"
- model: "black-forest-labs/flux-redux-dev"
- image_path: "~/Pictures/reference.png"
- num_outputs: 2

Inpainting (Fill)

Remove objects from image:
- prompt: "remove overhead wires, seamless sky"
- download_path: "~/Pictures/flux-gen"
- model: "black-forest-labs/flux-fill-pro"
- image_path: "~/Pictures/street.jpg"
- mask_path: "~/Pictures/street_mask.png"
- guidance: 30

Tool Reference

flux_models()

Returns list of available models with metadata, usage notes, and key input parameters.

Returns:

[
  {
    "model": "string",
    "display": "string",
    "kind": "string",
    "accepts_image": boolean,
    "notes": ["string"],
    "key_inputs": ["string"]
  }
]

flux_generate(...)

Generate images and save to local disk.

Required parameters:

• prompt (string) — text prompt describing the image
• download_path (string) — directory to save generated images

Optional parameters:

• model (string) — FLUX model to use (default: flux-1.1-pro-ultra)
• output_format (string) — output image format: "png" (default), "jpeg", or "webp"
• image_path (string) — local path or URL to input image (for models that accept images)
• mask_path (string) — path/URL to mask image for inpainting (Fill model)
• aspect_ratio (string) — e.g., "1:1", "16:9", "3:4"
• seed (integer) — random seed for reproducibility
• raw (boolean) — enable raw realism mode (Ultra model)
• num_outputs (integer) — number of images to generate
• output_quality (number) — quality setting (model-dependent)
• go_fast (boolean) — speed vs quality tradeoff (model-dependent)
• strength (number) — variation strength (Redux model)
• num_inference_steps (integer) — inference steps (Fill model)
• guidance (number) — guidance scale (Fill model)

Returns:

{
  "model": "black-forest-labs/flux-pro",
  "saved": ["/absolute/path/to/file_1.webp"],
  "urls": ["https://replicate.delivery/..."]
}

Model Selection Guide

Model	Use Case	Accepts Image	Speed	Quality
FLUX1.1 Pro Ultra	Best overall quality, large outputs, realism	No	Slower	Highest
FLUX1.1 Pro	Fast reliable default, commercial use	No	Fast	High
FLUX.1 Redux [dev]	Image variations, restyling	Yes	Fast	High
FLUX.1 Fill [pro]	Inpainting, outpainting	Yes + Mask	Medium	High
FLUX.1 Depth [dev]	Structure-preserving style transfer	Yes	Medium	High
FLUX.1 Canny [pro]	Sketch-to-image, edge control	Yes	Medium	High

Security

This MCP server implements multiple security measures:

Path Traversal Protection

• Download paths are validated and must be within:
  • User's home directory (~)
  • /tmp directory
  • Project's downloads/ folder
• Prevents writing files to arbitrary system locations

URL Validation

• Only HTTPS URLs allowed (no HTTP)
• Downloaded images must come from replicate.delivery domain only
• Prevents SSRF (Server-Side Request Forgery) attacks
• Validates redirect targets

Input Sanitization

• Model IDs validated against allowlist
• File paths normalized to prevent ../ attacks
• Error messages sanitized to prevent information disclosure

Error Handling

• Sensitive information (stack traces, paths) not exposed to clients
• Detailed errors logged server-side for debugging
• User-friendly error messages returned

Dependencies

• Regular security audits via npm audit
• Minimal dependency tree
• Official MCP SDK and Replicate client only

Troubleshooting

"REPLICATE_API_TOKEN is not set"

• Ensure the environment variable is exported or configured in your MCP client

"Model requires image_path"

• Redux, Fill, Depth, and Canny models require an input image
• Provide image_path parameter with local file or URL

Images not downloading

• Check that download_path directory is writable
• Verify you have sufficient disk space

"NSFW content detected"

• Replicate's safety filters blocked the content
• Try rephrasing your prompt

Development

Running locally

npm install
export REPLICATE_API_TOKEN="r8_..."
node index.js

Testing with MCP Inspector

npm install -g @modelcontextprotocol/inspector
mcp-inspector node index.js

Publishing to npm

npm version patch  # or minor, or major
npm publish

License

MIT

Credits

• Replicate for FLUX model hosting
• Black Forest Labs for FLUX models
• Model Context Protocol for the MCP SDK