FLUX MCP 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, ChatGPT, Cursor, Codex, Devin, and other MCP-compatible clients. No API code, no keys pasted into the conversation. Image generation and editing use FLUX 3 Image by default. For ChatGPT, follow the setup tab above. Account and workspace policies control custom connections; see OpenAI’s connection guide for the current interface. Start with a credit-balance check before generating media.

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, and inpainting-style edits through prompts.	Each entry in `requests` carries its own prompt and optional model and size settings. References go in `input_medias` as `{id}` for a prior generation or upload, or `{url}` for a public image. FLUX 3 Image accepts up to 10 references per entry.
`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. Designed to preserve the subject’s face, hair, and pose while changing the wearable.	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, size settings, and any reference images. 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.
`list_skills`	List the official BFL prompting guides.	Use the advertised names with `get_skill`.
`get_skill`	Read a prompting guide or selected sections.	Fetch relevant guidance before complex generation or editing requests.
`request_upload_url`	Create a signed upload URL and media ID.	PUT file bytes directly to the returned Storage URL, then reference the media ID in a generation.
`get_result`	Resume a submitted request and retrieve its result.	Viewers call this polling helper automatically. Some hosts expose it only to the app.
`get_references`	Retrieve input-reference previews for a generation.	App helper used by the viewer’s details dialog.
`refresh_image_url`	Renew a signed URL for an owned stored result.	App helper used when an old result URL expires.
`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.
`upscale_video`	Increase the resolution of a finished video.	Takes `input_video` as `{id}` or `{url}` and an `upscale_factor` from 1.5 to 3.0. Precise mode (`creativity: 0`) is the default; use creative mode only when you know the clip’s content. This works on finished clips, not just drafts.
`edit_video`	Change a finished video through a prompt.	Takes `input_video` and `prompt`. Source clips must be MP4, at most 15.05 seconds, and at least 160 pixels on each side. The output follows the source framing and duration, within the model’s 720p budget.

generate_image defaults to flux3_image (FLUX 3 Image) for generation and editing. Output size uses aspect_ratio and resolution, with 1k resolution by default and up to 4k available. For edits with no resolution set, the server uses the nearest tier to the first reference when it is bucket-hosted and its size can be read; otherwise it falls back to 1k.flux3_image_klein (FLUX 3 Image Klein) is the fast, cheap model in the same family. It sizes the same way and accepts the same 10 references, and it is the only FLUX 3 Image model that takes seed, steps (1 to 16, 16 by default) and output_format (jpeg or png).FLUX.2 models use the same aspect_ratio and resolution sizing, up to 2k, and take a fixed seed. Flex also accepts guidance from 1.5 to 10 and steps from 1 to 50. The full catalog, per-model reference-image limits, and the FLUX Tools are 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 request IDs first. generate_video returns pending entries in data.items, each with a request_id. 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

FLUX 3 Image plans the prompt before rendering, and 4k output can take several minutes. Large sets of images or complex edits also 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, quote the exact words in the prompt.
For print, poster, or wallpaper output, ask for 4k resolution.
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