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

Related MCP server: FLUX Image Generator MCP Server

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:

Edit Image

Edit this image to add a rainbow in the sky

Parameters:

Expand Image

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

Expand the image by 256 pixels on the right side

Parameters:

Save Image

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

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

Parameters:

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:

Pricing

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