FLUX MCP server

Connect FLUX. Most modern MCP clients can connect to https://mcp.bfl.ai directly and handle the OAuth flow on their own — pick your client from the tabs below. For stdio-only or OAuth-incompatible clients (for example Hermes), use the mcp-remote fallback tab. It runs locally, handles the browser OAuth flow, refreshes tokens for you, and exposes FLUX as a normal stdio server. Bring FLUX into the tools you already use. Generate options in parallel, edit attached images through prompts, branch into variations from any result you like, and generate video from the same conversation, inside Claude, Cursor, Codex, Windsurf, and any MCP-compatible client. No API code, no keys pasted into the conversation.

Pricing

You pay BFL directly. The organization selected during OAuth sign-in is billed for generated images. No shared quotas, no middleman. To change organizations, disconnect the connector and reconnect it. Current rates are listed at bfl.ai/pricing.

Tool reference

The MCP server exposes a small set of tools. Your client decides which to call based on your prompt — you do not need to invoke them by name. The reference is here for developers who want to know exactly what is available.

Show all tools

Tool	Purpose	Notes
`generate_image`	Generate one or up to 8 images in parallel. Covers text-to-image, edits, multi-reference composition, style transfer, inpainting-style edits, and outpainting through prompts.	Each entry in `requests` carries its own prompt, model, dimensions, seed, and up to 8 `input_image` slots. Outpainting uses `width`/`height` larger than the source.
`vto`	Virtual try-on. Dress a person, pet, or mascot in a garment, hat, sunglasses, shoes, bag, or any other wearable taken from a reference image. Face, hair, and pose stay as they were; only the worn item changes.	Takes a `person` image and a `garment` image, each as a prior `request_id` or a public URL. One garment slot per call, so merge a multi-piece outfit into a single reference image first.
`generate_variations`	Produce N more images “in the same direction” as a previous generation, identified by `request_id`.	Reuses the original prompt, model, dimensions, and any input image slots. Defaults to 4 variations, max 8.
`get_history`	List recent generations as a thumbnail grid with per-tile actions (Variations, Edit, copy, download).	Keyset pagination on `created_at` via `cursor`; supports `before` / `after` date filters and a `status` filter.
`get_credits`	Return the calling user’s remaining BFL credit balance.	Useful when a generation fails for billing reasons.
`generate_video`	Generate video with FLUX 3. Covers text-to-video, animating or morphing between supplied keyframe images, and continuing from an existing clip.	Each entry in `requests` sets `mode` (`t2v`, `i2v`, `v2v`) and a prompt, plus optional `duration` (5–20 seconds, or `auto`), `aspect_ratio`, and `resolution` (`hd` or `fhd`). Up to 4 clips per call. `generate_audio` is on by default. Returns a `request_id` immediately; see the video note below.
`enhance_video`	Re-render a finished draft at full quality, keeping the same composition, seed, and prompt plan.	Takes the `request_id` of a ready draft and finishes at `fhd` by default. This is the commit step of the draft-then-enhance loop.

Available models on generate_image: flux2_pro_preview (default), flux2_max (highest quality), flux2_klein_9b_preview (faster, up to 4 input images), flux2_flex (best for typography), flux2_klein_4b. The full catalog, per-model reference-image limits, and the FLUX Tools are also exposed as the bfl://models MCP resource.Video runs on flux3_video.Note that vto is its own tool, not a model. Ask for a try-on in plain language and your client routes there; passing vto as a model value to generate_image fails.

Video returns a request_id first. generate_video responds with {"status": "pending", "request_id": "…"} right away. Clips take minutes, and long ones can take considerably longer. Visual clients keep polling on their own. In a terminal client, ask again or have your agent call get_result(request_id="…") to pick the clip up.Draft first, then enhance. Setting draft: true renders a cheap hd pass so you can judge motion and timing before committing. When you like it, enhance_video re-renders that same draft at full quality. Drafts are hd only.

Troubleshooting

Tools do not appear after connecting

In Claude Desktop or Claude.ai, open Settings → Connectors and confirm the FLUX connector shows as Connected.
If the connection failed silently, remove the connector and add it again. Make sure pop-ups are not blocked so the OAuth window can open.
In Claude Code, run claude mcp list to confirm the server is registered.
In Codex, run codex mcp list to confirm the FLUX server is registered, then start a new Codex session.

Refreshing tools or reconnecting the server

If the FLUX tools are not responding, or you just installed or updated the connector, refreshing the connection can help.

Claude.ai / Claude Desktop: open Settings → Connectors, toggle the FLUX connector off and on, or click Reconnect. Restarting Claude Desktop is another way to pick up a fresh tool list.
Claude Code: run /mcp to view server status and reauthenticate. To rebuild the registration entirely, run claude mcp remove FLUX followed by claude mcp add --transport http FLUX https://mcp.bfl.ai.
Codex: run codex mcp login FLUX to reauthenticate. To rebuild the registration entirely, run codex mcp remove FLUX followed by codex mcp add FLUX --url https://mcp.bfl.ai — the OAuth browser flow runs automatically on add.
mcp-remote clients: clearing the cached OAuth tokens with rm -rf ~/.mcp-auth and restarting the client triggers a fresh browser sign-in.
To confirm the tools are live, ask your MCP client something simple like “check my BFL credits”.

Authentication or billing errors

Make sure you have a BFL account at bfl.ai.
Disconnect and reconnect the MCP server to redo the OAuth flow.
Check that the selected organization has sufficient credits.
Ask your MCP client to check your BFL credits if you want to verify the current balance.

A generation keeps loading

Large sets of images, FLUX.2 [max], or complex edits can take longer than smaller generations. In Claude and other visual MCP clients, the image view keeps updating automatically.Video is slower by nature. You can expect a video to take minutes rather than seconds, on top of that duration and fhd resolution increase generation time. If your client has stopped showing progress, ask it to check the request again, or call get_result with the request_id from the original response. Use draft: true while you are still iterating.

Attached image editing fails

Your MCP client needs permission to upload attached images to BFL. If your client blocks outbound HTTPS from its sandbox, allow the *.bfl.ai domain or use a public image URL instead.

Image quality issues

Use detailed prompts. Describe subject, style, composition, and lighting.
For typography or readable text, ask for FLUX.2 [flex].
For hero shots or final assets, ask for FLUX.2 [max].
For edits, say what should stay unchanged as well as what should change.

Switching the billed organization

Disconnect the FLUX connector in your client and reconnect it. The OAuth flow will prompt you to select an organization again.

Prompt Tips

Front-load the subject. Put the most important object, person, or scene first.
Describe lighting. “Soft golden hour light” or “overcast diffused studio light” gives the model useful direction.
Use hex colors. #FF6B6B (coral pink) is more precise than “pinkish red”.
Quote rendered text. Use exact quoted strings for typography, labels, posters, and signs.
Avoid negative prompts. FLUX responds to what you describe, not a list of what to avoid.
Iterate from results. Use Variations for alternatives or Edit to keep refining a generated image.
For video, name one thing that happens. A clip needs a subject, a camera behaviour, and a single motivated event. Describe the sound you want too, since audio is generated with the picture.

Agent Skills

MCP and Agent Skills solve different problems:

	MCP	Agent Skills
What it does	Generates, edits, varies, and browses images and video directly in chat	Teaches your coding agent how to write FLUX API code and how to direct FLUX generations
Best for	Creative work inside Claude or another MCP client	Building applications that call the FLUX API
Install on	Claude Desktop, Claude.ai, Claude Code, and MCP-compatible clients	Claude Code, Cursor, Windsurf, and other skill-compatible tools

Installation

Claude Code
Cursor
Other Tools

/plugin marketplace add black-forest-labs/skills
/plugin install flux-image-best-practices@black-forest-labs
/plugin install flux-3-video@black-forest-labs

npx skills add black-forest-labs/skills

Or add manually by placing the skill files in .cursor/skills/ in your project.

npx skills add black-forest-labs/skills

Skills follow the open agentskills.io specification and work with any compatible tool.

What Your Agent Learns

flux-image-best-practices teaches prompting patterns: prompt structure, lighting vocabulary, hex colors, typography, model selection, and why FLUX does not use negative prompts. bfl-api teaches production API patterns: async generation, rate-limit handling, URL expiration, regional endpoints, webhook verification, and error handling. flux-3-video is a set of six skills for video work. flux-3-video routes a request to the ones it needs; flux-3-prompt-doctor catches the decisions that change the payload before anything is generated; flux-3-cinematic-inserts covers shot craft for text-to-video; flux-3-keyframes-continuation covers building from supplied images or extending an existing clip; flux-3-audio-dialogue covers ambience, effects, and speech; and flux-3-generate covers submitting, polling, drafts, and downloads.

Updating

npx skills update black-forest-labs/skills

Get Started

Account Management

FLUX 3

FLUX.2

FLUX Tools

API Integration

Training

Legacy Models

Pricing

Tool reference

Troubleshooting

Prompt Tips

Agent Skills

Installation

What Your Agent Learns

Updating

Resources

​Pricing

​Tool reference

​Troubleshooting

​Prompt Tips

​Agent Skills

​Installation

​What Your Agent Learns

​Updating

​Resources

Pricing

Tool reference

Troubleshooting

Prompt Tips

Agent Skills

Installation

What Your Agent Learns

Updating

Resources