Skip to main content
Glama
kmaurinjones

FLUX MCP Server

by kmaurinjones
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

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

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesText prompt describing the image
download_pathYesDirectory to save generated images
modelNoFLUX model to useblack-forest-labs/flux-1.1-pro-ultra
image_pathNoLocal path or URL to input image (for image-accepting models)
mask_pathNoLocal path or URL to mask for inpainting (Fill model)
aspect_ratioNoAspect ratio (e.g., '1:1', '16:9', '3:4')
seedNoRandom seed for reproducibility
rawNoEnable raw realism mode (Ultra model)
num_outputsNoNumber of images to generate
output_qualityNoQuality setting (model-dependent)
go_fastNoSpeed vs quality tradeoff
strengthNoVariation strength (Redux model)
num_inference_stepsNoInference steps (Fill model)
guidanceNoGuidance scale (Fill model)
output_formatNoOutput image format (png, jpeg, or webp)png

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions 'save files to download_path' which indicates file system writing, but doesn't disclose important behaviors like: whether this is a long-running operation, rate limits, authentication requirements, error handling, or what happens if download_path doesn't exist. For a complex 15-parameter image generation tool, this is inadequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core functionality. Every word earns its place: 'Generate an image' (action), 'with a FLUX model' (technology), 'via Replicate' (service), 'and save files to download_path' (output behavior). No wasted words or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex image generation tool with 15 parameters and no annotations or output schema, the description is insufficient. It doesn't explain what the tool returns (file paths? success status?), doesn't mention error conditions, and provides no context about model-specific behaviors. The 100% schema coverage helps, but the description should do more to guide usage of such a feature-rich tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 15 parameters thoroughly. The description mentions 'download_path' but adds no additional semantic context beyond what's in the schema. It doesn't explain relationships between parameters (e.g., which models accept image_path) or provide usage examples. Baseline 3 is appropriate when schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Generate an image') and resource ('with a FLUX model via Replicate'), specifying the service provider. It distinguishes from the sibling tool 'flux_models' by focusing on image generation rather than model listing. However, it doesn't explicitly contrast with the sibling tool in the description text itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. There's no mention of when to choose specific models, when to use image_path or mask_path parameters, or any prerequisites for usage. The sibling tool 'flux_models' exists but isn't referenced in usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

flux_modelsB

List supported FLUX models with usage notes and key inputs

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions that the tool lists models with 'usage notes and key inputs,' which gives some context about the output format. However, it doesn't describe critical behavioral traits such as whether this is a read-only operation, if it requires authentication, rate limits, or how the data is structured (e.g., pagination, sorting). For a tool with zero annotation coverage, this leaves significant gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core action ('List supported FLUX models') and adds value with 'usage notes and key inputs.' There is no wasted language, and it effectively communicates the essential information in a compact form.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is adequate but could be more complete. It covers the purpose and hints at output content, but without annotations or an output schema, it should ideally specify behavioral aspects like read-only nature or data format. For a low-complexity tool, it's minimally viable but lacks depth in transparency.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0 parameters with 100% coverage, meaning there are no parameters to document. The description doesn't need to add parameter semantics, so it naturally meets the baseline. It appropriately focuses on the tool's purpose without unnecessary parameter details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('List') and resource ('supported FLUX models'), along with additional context about what information is included ('usage notes and key inputs'). It distinguishes itself from the sibling tool 'flux_generate' by focusing on listing models rather than generating content. However, it doesn't explicitly contrast with the sibling beyond the different action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context through 'usage notes and key inputs,' suggesting this tool is for discovering available models and their characteristics. It doesn't provide explicit guidance on when to use this versus 'flux_generate' (e.g., 'use this to find models before generating'), nor does it mention any prerequisites or exclusions. The usage is implied but not clearly articulated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updates
    • First observedflux_generate
    • First observedflux_models
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers