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:

From npm (after publishing):

Claude Desktop

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

For local development:

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

Local Development

Installation

From npm (after publishing)

From source

Usage

List available models

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

Returns:

Generate images

Text-to-image (Pro)

Or specify a different format:

Text-to-image (Ultra - highest quality)

Image variation (Redux)

Inpainting (Fill)

Tool Reference

flux_models()

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

Returns:

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

Testing with MCP Inspector

Publishing to npm

License

MIT

Credits

• Replicate for FLUX model hosting

• Black Forest Labs for FLUX models

• Model Context Protocol for the MCP SDK