kmaurinjones/flux-mcp

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

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