FLUX MCP Server
Provides access to FLUX image generation models via Replicate's API, enabling text-to-image generation, image variations, inpainting/outpainting, depth-guided editing, and edge-guided generation from sketches across six different FLUX model variants.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@FLUX MCP Server create a serene mountain landscape at sunset with pine trees"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
flux_models— list models with usage notesflux_generate— generate images, save locally, return file paths + URLs
Related MCP server: Image Generation MCP Server
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.jsFrom npm (after publishing):
claude mcp add --scope user flux-mcp --env REPLICATE_API_TOKEN=r8_your_token_here -- npx flux-mcp@latestClaude 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.jsInstallation
From npm (after publishing)
npm install -g flux-mcpFrom source
git clone https://github.com/kmaurinjones/flux-mcp.git
cd flux-mcp
npm install
npm linkUsage
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: trueImage 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: 2Inpainting (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: 30Tool 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 imagedownload_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 reproducibilityraw(boolean) — enable raw realism mode (Ultra model)num_outputs(integer) — number of images to generateoutput_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 (
~)/tmpdirectoryProject's
downloads/folder
Prevents writing files to arbitrary system locations
URL Validation
Only HTTPS URLs allowed (no HTTP)
Downloaded images must come from
replicate.deliverydomain onlyPrevents SSRF (Server-Side Request Forgery) attacks
Validates redirect targets
Input Sanitization
Model IDs validated against allowlist
File paths normalized to prevent
../attacksError 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 auditMinimal 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_pathparameter with local file or URL
Images not downloading
Check that
download_pathdirectory is writableVerify 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.jsTesting with MCP Inspector
npm install -g @modelcontextprotocol/inspector
mcp-inspector node index.jsPublishing to npm
npm version patch # or minor, or major
npm publishLicense
MIT
Credits
Replicate for FLUX model hosting
Black Forest Labs for FLUX models
Model Context Protocol for the MCP SDK
Available Tools
2 toolsflux_generateC
Generate an image with a FLUX model via Replicate and save files to download_path
Inputs: prompt (required), download_path (required), model, image_path, +11 more.
flux_modelsB
List supported FLUX models with usage notes and key inputs
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: one generates images, while the other lists available models. There is no overlap in functionality, and an agent can easily differentiate between them based on their names and descriptions.
Both tools follow a consistent 'flux_' prefix with descriptive suffixes ('generate' and 'models'), using snake_case throughout. This pattern is predictable and enhances readability for agents.
With only two tools, the server feels thin for an image generation domain. While it covers generation and model listing, it lacks operations for managing generated images (e.g., delete, list, update) or handling other aspects like prompts or settings, making the scope incomplete.
The toolset is severely incomplete for an image generation server. It includes generation and model listing but misses essential operations such as retrieving, deleting, or modifying generated images, and lacks tools for prompt management or configuration, leaving significant gaps in the workflow.
Related MCP Connectors
Generate images and video from Claude with one API key.
Generate and edit images and create short videos inside Claude. Prepaid credits, no subscription.
Turn Claude into a creative studio: DNA-locked characters, images, video, voiceover — 55 tools.
Generate images, videos, music & lip sync with 200+ AI models (Flux, Veo 3, Kling, Suno)
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides image generation capabilities using the Flux Schnell model on Replicate, allowing users to create images from text prompts.2MIT
- AlicenseBqualityFmaintenanceProvides image generation capabilities for Claude using the Replicate Flux model, allowing users to create images from text prompts with customizable parameters like aspect ratio and output format.151MIT
- AlicenseNot gradedqualityNot gradedmaintenanceEnables high-quality image generation with advanced text rendering and contextual understanding using FLUX.1 Kontext Max through the Replicate API. Supports text-to-image generation, image editing, multiple aspect ratios, and automatically downloads generated images locally.1-
- FlicenseNot gradedqualityDmaintenanceImage generation for Claude using every model on fal.ai, inline in conversations. Supports FLUX Schnell, Ideogram, SDXL, and more with privacy option via Venice.ai.-