flux-mcp
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 generate an image of a snowy forest with a red fox and a trail sign"
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
An MCP server that lets any MCP client (Claude Code, Claude Desktop, Open WebUI, your own agents) generate and edit images with FLUX 3 Image Klein, running locally in ComfyUI.
MCP client ──streamable HTTP + bearer token──▶ flux-mcp :8300 ──HTTP──▶ ComfyUI :8188 (GPU)flux-mcp has no GPU or model code: it fills a ComfyUI workflow, submits it, waits, and returns a JPEG preview plus a link to the full-resolution PNG. It is built on mcp-service-kit, which provides the transports, CLI and configuration.
Tools
Tool | What it does |
| Text to image. |
| Edit an image, or compose a new one from up to 10 reference images. |
| Enlarge 2× or 4× with Real-ESRGAN (output ≤ 8192 px per side) |
| Cut out the subject onto a transparent PNG (BiRefNet) |
| Show a stored image again with its prompt, seed, caption and model; without an id, the latest image (recovers a call that timed out on the client) |
| Free the models' GPU memory now; they reload on the next request |
| Workflows and the model files ComfyUI sees |
| ComfyUI version, queue length, free memory, whether models are loaded and when they will be unloaded |
Each image result contains a text block with the seed and full-resolution URL
(<FLUX_PUBLIC_BASE_URL>/images/<id>.png), one JPEG preview (longest side ≤ 1024 px) per image,
and structured content {seed, width, height, images: [{id, url}]}.
What made each image. Results include the caption the prompt upsampler actually sent to the
model, so you can see how a request was interpreted. Every stored PNG also carries a flux-mcp
iTXt chunk with JSON: tool, prompt, seed, quality, size, model, steps, input images, boxes,
caption and time. get_image shows it, as does any tool that lists PNG text chunks (for
example exiftool image.png, or Pillow's Image.open(path).text["flux-mcp"]).
Prompt upsampler. FLUX 3 Klein expects full scene captions; a short prompt as typed gives
generic results. By default (enhance_prompt=true) the request first goes through Black Forest
Labs' Qwen3.5-9B prompt upsampler. Turn it off only when the client writes a complete caption.
Limits (configurable): sides 256–4096 px (rounded to multiples of 16), up to 4 images per call, prompts up to 4000 characters, edit inputs up to 20 MB, 300 s per call.
Related MCP server: Universe Imagine MCP
Layout with bounding boxes
generate_image and edit_image take optional boxes. Each box is
{"bbox": [y_min, x_min, y_max, x_max], "desc": "...", "text": "..."} on a 0–1000 grid with
(0, 0) at the top left, stretched over the canvas; text is optional and rendered verbatim.
Boxes guide placement and scale; they are not hard masks.
{"prompt": "a snowy forest clearing", "width": 1536, "height": 1024, "boxes": [
{"bbox": [350, 60, 950, 420], "desc": "a red fox sitting, facing right"},
{"bbox": [250, 600, 800, 950], "desc": "a weathered wooden trail sign", "text": "FOX TRAIL"}]}For edit_image, boxes mark regions of the first image and are named obj_1, obj_2, …
in order, so the prompt can say "remove obj_1" or "replace obj_2 with a bicycle". Behind the
scenes the prompt upsampler switches to BFL's box-aware system prompts
(workflows/prompts/*_bbox.txt); with enhance_prompt=false the element table is appended to
your caption, as ComfyUI's Flux3LayoutPrompt does.
Uploading your own images
Tools take image ids, so upload an image first and use the returned id:
curl -H "Authorization: Bearer $FLUX_MCP_TOKEN" -F file=@photo.jpg http://10.0.0.96:8300/upload
# {"id": "1329da32…", "url": "http://10.0.0.96:8300/images/1329da32….png", "width": 1776, "height": 1184}Agents with a shell (Claude Code, Cline, opencode) can run this themselves; the server's
instructions tell them how. In a browser, open http://10.0.0.96:8300/upload, paste the token,
and drop images to get their ids. Images pasted into a chat cannot be forwarded to a tool: the
model only receives them, it cannot hand the bytes on. Uploads are limited to
FLUX_MAX_INPUT_BYTES (20 MB) and stored as PNG.
Models
The weights are in the gated repo
black-forest-labs/flux-3-image-klein-comfy
(FLUX Kommunity License; accept it on that page with the account your HF_TOKEN belongs to).
cd /mnt/shared/huggingface/comfyui # the MODELS_DIR mounted into ComfyUI
for f in diffusion_models/flux3-image-klein-nvfp4.safetensors \
diffusion_models/flux3-image-klein-base-nvfp4.safetensors \
text_encoders/qwen3vl_4b_bf16.safetensors \
text_encoders/qwen3.5_9b_flux3_prompt_upsampler_w4a8.safetensors \
vae/flux2-vae.safetensors; do
uvx --from 'huggingface_hub[cli]' hf download black-forest-labs/flux-3-image-klein-comfy "$f" --local-dir .
done
uvx --from 'huggingface_hub[cli]' hf download Comfy-Org/BiRefNet background_removal/birefnet.safetensors --local-dir .
mkdir -p upscale_models && curl -L -o upscale_models/RealESRGAN_x4plus.pth \
https://github.com/xinntao/Real-ESRGAN/releases/download/v0.1.0/RealESRGAN_x4plus.pthFile | Size | Role |
| 5.3 GB | distilled transformer, NVFP4 (Blackwell) |
| 8.9 GB | text encoder |
| 6.7 GB | prompt upsampler |
| 0.3 GB | VAE |
| 5.3 GB | undistilled base model, for |
| 64 MB | upscaler (BSD-3-Clause) |
| 0.4 GB | background removal (MIT) |
To use other files (int8, bf16, the base checkpoint), edit the loader nodes in
workflows/*.json.
Performance (DGX Spark / GB10, next to a running vLLM)
Measured through the MCP endpoint, 1024×1024, one image, 16 steps:
Call | Time |
First call after ComfyUI starts (loads ~21 GB of weights from NFS) | ~260 s |
| ~17 s |
| ~8.5 s |
| ~29 s |
| ~45 s |
| ~27 s |
| ~46 s (~58 s when the base model loads) |
| ~10 s / ~11 s |
| ~2 s |
| ~25 s |
Memory: an unload (idle or unload_models) gave back about 18–19 GB. With the fast-mode models loaded, the host's available memory dropped by about 10 GB
(the rest came out of page cache); with the base model resident as well, about 27 GB stayed
available next to vLLM. Clients with a short tool-call timeout should allow at least 60 s
(120 s for quality="high"), or more for the first call; flux-mcp sends progress notifications
while it waits.
Run
cp .env.example .env
sed -i "s/^FLUX_MCP_TOKEN=.*/FLUX_MCP_TOKEN=$(openssl rand -hex 32)/" .env
docker compose up -d --build
docker compose logs -f flux-mcpThe ComfyUI web UI is at http://<host>:8188, the MCP endpoint at http://<host>:8300/mcp.
Both are meant for the LAN only: ComfyUI has no authentication, and image URLs are protected
only by their random ids.
Configuration (environment or .env):
Variable | Default | |
| — | bearer token; required for HTTP unless |
|
| compose sets |
|
| base of the image URLs returned to clients |
|
| |
|
| unload ComfyUI's models after this many idle seconds, freeing memory for other GPU users such as vLLM ( |
|
| |
| see | limits |
|
| from mcp-service-kit (the image sets |
Without Docker (server only)
uv sync
FLUX_MCP_TOKEN=... FLUX_COMFYUI_URL=http://10.0.0.96:8188 uv run flux-mcp --mode http --port 8300
uv run flux-mcp --mode stdio # for local clients that launch the server themselvesConnect a client
Any MCP client that supports streamable HTTP: URL http://10.0.0.96:8300/mcp, header
Authorization: Bearer <FLUX_MCP_TOKEN>.
Claude Code
claude mcp add --transport http flux http://10.0.0.96:8300/mcp \
--header "Authorization: Bearer $FLUX_MCP_TOKEN"Claude Desktop (claude_desktop_config.json, via stdio on the same machine as ComfyUI or
with FLUX_COMFYUI_URL pointing at it):
{
"mcpServers": {
"flux": {
"command": "uv",
"args": ["--directory", "/path/to/flux-mcp", "run", "flux-mcp", "--mode", "stdio"],
"env": {"FLUX_COMFYUI_URL": "http://10.0.0.96:8188"}
}
}
}In stdio mode, image URLs point at FLUX_PUBLIC_BASE_URL, which only works while an HTTP
instance serves the same FLUX_OUTPUT_DIR; the inline previews always work.
Open WebUI: Settings → External Tools → add an MCP (Streamable HTTP) server with the URL above and the bearer token.
MCP Inspector: npx @modelcontextprotocol/inspector, transport "Streamable HTTP", same URL
and header.
Workflows
workflows/flux3_klein_t2i.json and flux3_klein_edit.json are ComfyUI API-format graphs,
flattened by hand from Black Forest Labs' Klein templates (MIT, in the model repo's
workflows/). workflows/nodes.yaml maps tool parameters to node inputs and describes the
upsampler nodes and the reference-image inputs (extra references get copies of the image
loader node, wired into the reference and upsampler nodes), so you can swap models or add a workflow without code changes. To start from
a workflow built in the web UI, use Export (API) and map its node ids in nodes.yaml.
Development
uv sync
uv run pytest # fake ComfyUI over httpx.MockTransport; no GPU needed
uv run ruff checkHow the pieces fit together, with diagrams: docs/ARCHITECTURE.md.
Layout follows mcp-service-kit's example: server.py (server, auth, main), service.py
(tool discovery, image route), features/*/tool.py (one tool each), flux_service.py and
comfy_client.py (business logic, no MCP imports), workflows.py, images.py, config.py.
License
Code: Apache License 2.0, see LICENSE. FLUX 3 Image Klein weights: FLUX Kommunity License. Text encoder and prompt upsampler: Apache-2.0. Workflow templates: MIT (Comfy Org).
Available Tools
8 toolsedit_imageEdit ImageA
Edit an image, or combine several reference images, with FLUX 3 Image Klein
With one image, describe the change ("make the sky stormy", "add a red scarf to the dog"). With several, say what to take from each by order ("the woman from the first image standing in the forest from the second image"). Returns a JPEG preview of each result plus the URL and id of the full-resolution PNG.
Inputs: images (required), prompt (required), seed, boxes, +6 more.
generate_imageGenerate ImageA
Generate images from a text description with FLUX 3 Image Klein
Returns a JPEG preview of each image plus the URL and id of the full-resolution PNG. Use the id with edit_image to refine a result.
Inputs: prompt (required), seed, boxes, count, +5 more.
get_imageGet ImageA
Show a stored image again, with how it was made
Returns the preview, URL and stored details (prompt, seed, upsampled caption, model). Without an id it returns the most recent image, which also recovers the result of a call that timed out on the client side.
Inputs: image.
list_modelsList ModelsA
List the workflows this server runs and the model files ComfyUI can see
Inputs: no named parameters. Returns: object
remove_backgroundRemove BackgroundA
Cut out the main subject and make the background transparent (BiRefNet)
Returns a transparent PNG (the preview shows it on white) plus its URL and id.
Inputs: image (required).
server_statusServer StatusA
Report whether ComfyUI is up, its queue, free memory and whether models are loaded
Inputs: no named parameters. Returns: object
unload_modelsUnload ModelsA
Free the GPU memory held by the image models now
The models reload automatically on the next request, which then takes longer. The server also does this by itself after a period without requests.
Inputs: no named parameters. Returns: object
upscale_imageUpscale ImageA
Enlarge an image 2x or 4x with an upscaling model (Real-ESRGAN)
Adds sharpness rather than new content; use it for prints and wallpapers. Takes a few seconds. Returns a preview plus the URL and id of the full-resolution PNG.
Inputs: image (required), factor.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a clearly distinct action on the image pipeline: generate, edit, upscale, background removal, retrieve, plus model/server administration. The descriptions explicitly delineate the boundaries (e.g. upscale 'adds sharpness rather than new content', edit requires an id from generate), so an agent can select correctly without guessing.
Seven of eight tools follow a clean verb_noun snake_case pattern (generate_image, edit_image, upscale_image, remove_background, get_image, list_models, unload_models). The only deviation is 'server_status', which is noun-first, but it remains readable and unambiguous.
Eight tools is well within the ideal 3-15 range and every tool earns its place: four core image operations, one retrieval tool, and three operational/admin tools. Nothing looks redundant or like padding.
The core lifecycle (generate → edit → upscale → cutout → retrieve) is fully covered, along with model listing and GPU management. Minor gaps remain: there is no way to enumerate stored images (only fetch by id or 'most recent') and no delete/cleanup operation, but agents can work around these using returned ids.
Maintenance
Related MCP Connectors
MCP server for Flux AI image generation
Official FLUX MCP server. Generate, edit, vary, and browse images from Black Forest Labs.
Generate AI images and videos from any compatible MCP client.
Generate images from Claude, ChatGPT, Cursor and Codex with 12 top AI image models. Up to 4 images per call, SVG vectorization, background removal, upscaling and image-to-video. Remote MCP with OAuth, no API keys.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server for ComfyUI — text-to-image, variations, img2img refine, upscale, image proxy, and workflow runner.15145 npm3MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI image generation from text prompts by wrapping local ComfyUI as a Streamable HTTP MCP server, supporting synchronous generation, queue management, and history tracking.1MIT
- AlicenseNot gradedqualityDmaintenanceEnables MCP clients to generate images using local ComfyUI with FLUX.2 Klein models optimized for Apple Silicon, plus model management and system diagnostics.MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to generate and edit images using local Stable Diffusion models in ComfyUI, with tools for text-to-image, img2img, ControlNet, UI frames, upscaling, and background removal—no cloud API or API key required.MIT