Flux

You will run the Flux MCP Server to generate high-quality FLUX images using automatic model unloading and VRAM-aware switching. This server lets you generate images from MCP-compatible clients or directly from the CLI, with smart memory management and a seamless experience between local and integrated workflows.

How to use

You can use Flux MCP Server in two ways: as a local MCP server that speaks to MCP-compatible clients, or directly from the command line for offline, private generation. In MCP mode, you register the server with your MCP client so you can request image generation using natural language prompts or structured tool calls. In CLI mode, you run the flux commands yourself and manage generation end-to-end.

Practical workflows include: 1) Generating images on demand from an MCP client, with automatic model loading and unloads to save VRAM; 2) Running fully offline from the terminal for quick experiments; 3) Iterating prompts with adjustable steps, guidance, and dimensions. The server automatically selects the best VRAM strategy based on your GPU, and can unload the model after inactivity to preserve power.

How to install

Prerequisites you need before installing Flux MCP Server: Python 3.10 or newer, an NVIDIA GPU with enough VRAM, CUDA toolkit, and PyTorch with CUDA support.

Step-by-step installation and setup:

# 1. Clone the Flux MCP project directory
cd /path/to/flux-mcp

# 2. Install dependencies using UV (recommended)
uv sync

# Alternatively, install in editable mode with Python
pip install -e .

# 3. Create and configure environment variables
cp .env.example .env
# Edit .env to set FLUX_OUTPUT_DIR and other preferences

Configuration and usage notes

Your configuration is controlled via a local environment file. The key options include model selection, output directory, and auto-unload behavior. You can switch models and adjust timeouts at runtime, without restarting the server.

# Auto-unload timeout in seconds (default: 300 = 5 minutes)
FLUX_UNLOAD_TIMEOUT=300

# Output directory for generated images
FLUX_OUTPUT_DIR=/path/to/flux_output

# Optional: Custom HuggingFace cache directory
# FLUX_MODEL_CACHE=/path/to/cache

# Model selection (choose default model)
# FLUX_MODEL_ID=black-forest-labs/FLUX.1-dev
# FLUX_MODEL_ID=black-forest-labs/FLUX.2-dev

# Default generation parameters (model-specific smart defaults apply automatically)
# FLUX_DEFAULT_STEPS=50
# FLUX_DEFAULT_GUIDANCE=7.5

MCP server registration

Register Flux MCP Server with your MCP client to enable generation through conversational interfaces. Two common options are provided below.

# Claude Desktop (example for local MCP integration)
"mcpServers": {
  "flux": {
    "command": "uv",
    "args": [
      "--directory",
      "/absolute/path/to/flux-mcp",
      "run",
      "flux-mcp"
    ]
  }
}

# Alternatively, if Flux MCP is installed as a Python package
"mcpServers": {
  "flux": {
    "command": "python",
    "args": [
      "-m",
      "flux_mcp.server"
    ]
  }
}

CLI usage and MCP integration overview

Whether you use the MCP server or the CLI, you share a common configuration and output directory. The CLI provides a completely offline workflow for generation and includes an interactive mode for batch work, while the MCP server enables integration with conversational clients to generate images via natural language prompts.

Troubleshooting and tips

If you encounter CUDA memory errors, try using a memory-efficient configuration, or reduce image size or steps. You can manually unload the model to free VRAM and adjust the auto-unload timeout to suit your workflow.

If a model download fails, ensure internet connectivity and consider setting a larger local cache for models.

Tools exposed by the MCP server

The server exposes generation and memory management tools you can call from MCP clients.

Notes on performance and VRAM management

The server automatically detects available VRAM and selects a mode to balance performance and memory usage. It supports full GPU mode on 24GB+ cards, CPU offload on mid-range GPUs, and sequential CPU offload for limited VRAM. Automatic unloads save power, while lazy loading minimizes startup time.

Available tools

generate_image

Generate an image from a text prompt using FLUX.1-dev or FLUX.2-dev with configurable steps, guidance, and image size.

unload_model

Immediately unload the FLUX model from GPU memory to free VRAM.

get_status

Check the current status of the FLUX generator, including load state and VRAM usage.

set_timeout

Change the auto-unload timeout at runtime to optimize resource usage.