BFL Flux MCP Server

Minimal Python MCP server for Black Forest Labs Flux image generation API.

Features

• Seven comprehensive tools:

  • generate_image - Text-to-image with model selection
  • edit_image - Image editing with natural language
  • expand_image - Directional outpainting (add pixels to any side)
  • create_variation - Create variations of an image using Redux (image_prompt)
  • save_image - Download and save images before URLs expire
  • check_credits - Verify API key and credit balance
  • list_finetunes - View your custom finetuned models

• All Flux models supported:

  • Generation: flux-pro-1.1 (default), flux-pro-1.1-ultra, flux-2-pro, flux-2-flex, flux-2-max, flux-pro, flux-dev
  • Editing: kontext-pro, kontext-max, fill-pro
  • Expansion: expand-pro

• Full API parameter support:

  • Aspect ratio or custom dimensions
  • Prompt upsampling for enhanced output
  • Output format (PNG/JPEG)
  • Safety tolerance levels
  • Model-specific: guidance, steps, raw mode

Installation

# With uv (recommended)
uv sync

# With pip
pip install -e .

Configuration

Get your API key at api.bfl.ml

export BFL_API_KEY="your-api-key-here"

Claude Code / MCP Config

Add to .mcp.json:

{
  "mcpServers": {
    "bfl-flux": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/bfl-flux-mcp", "bfl-flux-mcp"],
      "env": {
        "BFL_API_KEY": "${BFL_API_KEY}"
      }
    }
  }
}

Or with uvx (once published):

{
  "mcpServers": {
    "bfl-flux": {
      "command": "uvx",
      "args": ["bfl-flux-mcp"],
      "env": {
        "BFL_API_KEY": "${BFL_API_KEY}"
      }
    }
  }
}

Usage

Check Credits

Verify your API key is working and check balance:

Check my BFL credits

Generate Image

Generate an image of a mountain landscape at sunset, photorealistic style

Parameters:

Parameter	Description	Default
prompt	Text description (required)	-
model	Model to use	flux-pro-1.1
aspect_ratio	1:1, 16:9, 9:16, 4:3, 3:4, 21:9, 9:21	1:1
width/height	Custom dimensions (multiple of 16, max 2048)	-
seed	For reproducibility	-
safety_tolerance	0 (strict) to 6 (permissive)	2
prompt_upsampling	Enhance prompt for richer output	false
output_format	png or jpeg	png
guidance	Prompt adherence 1.5-10 (flux-2-flex only)	-
steps	Generation steps 1-50 (flux-2-flex only)	-
raw	Raw mode (flux-pro-1.1-ultra only)	false

Edit Image

Edit this image to add a rainbow in the sky

Parameters:

Parameter	Description	Default
prompt	Edit instructions (required)	-
image	Base64-encoded image or URL (required)	-
model	kontext-pro, kontext-max, fill-pro	kontext-pro
aspect_ratio	Output aspect ratio	preserve
seed	For reproducibility	-
safety_tolerance	0-2	2

Expand Image

Expand an image by adding pixels to any side (outpainting):

Expand the image by 256 pixels on the right side

Parameters:

Parameter	Description	Default
image	Image to expand: path, URL, or base64 (required)	-
prompt	Optional guidance for the expansion	-
top	Pixels to add to top (0-2048)	0
bottom	Pixels to add to bottom (0-2048)	0
left	Pixels to add to left (0-2048)	0
right	Pixels to add to right (0-2048)	0
seed	For reproducibility	-
safety_tolerance	0-6	2
output_format	png or jpeg	png

Save Image

Download and save a generated image before the URL expires (10 min):

Save that image to /path/to/logo.png

Parameters:

Parameter	Description	Default
url	Image URL from generate/edit result (required)	-
path	Destination file path (required)	-

List Finetunes

View your custom finetuned models:

Show my finetuned models

No parameters required.

Create Variation

Create variations of an existing image that maintain its essence while applying optional text guidance:

Create a variation of this image with a warmer color palette

Parameters:

Parameter	Description	Default
image	Source image: path, URL, or base64 (required)	-
prompt	Optional text guidance for the variation	-
model	flux-pro-1.1, flux-pro-1.1-ultra, flux-dev	flux-pro-1.1
aspect_ratio	Output aspect ratio	1:1
seed	For reproducibility	-
safety_tolerance	0-6	2
output_format	png or jpeg	png

Pricing

Model	Credits	USD
flux-pro-1.1	4	$0.04
flux-pro-1.1-ultra	6	$0.06
flux-2-pro	5	$0.05
flux-2-flex	1-5	$0.01-0.05
flux-2-max	6	$0.06
kontext-pro	4	$0.04
kontext-max	8	$0.08
expand-pro	4	$0.04

1 credit = $0.01 USD

Note: Credits used are shown in tool responses when available.

Development

# Install with dev dependencies
uv sync --extra dev

# Run linter
uv run ruff check .

# Format code
uv run ruff format .

# Run tests
uv run pytest -v

# Run tests with coverage
uv run pytest --cov=bfl_flux_mcp --cov-report=term-missing

License

MIT - see LICENSE

Links

• BFL API Documentation
• BFL Playground (free testing)
• GitLab Repository
• GitHub Mirror