Skip to main content
Glama

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

Related MCP server: Image Generation MCP Server

Prerequisites

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

Available Tools

2 tools
flux_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

    B3.2/5.0

    Scored across 2 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness2/5

    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

    Related MCP Servers