flux-bfl-mcp

A Model Context Protocol (MCP) server for FLUX.2 image generation and editing using the BFL (Black Forest Labs) API. This server provides two powerful tools to generate and edit images through AI.

Features

🔧 Tools

flux_generate

Generate images using FLUX.2 AI models.

Parameters:

• prompt (required): Text description of the image to generate
• model (optional): FLUX.2 model to use ("pro" or "flex", default: "pro")
• width (optional): Output width in pixels (multiple of 16, default: 1024)
• height (optional): Output height in pixels (multiple of 16, default: 1024)
• safety_tolerance (optional): Moderation level (0-5, default: 2)
• seed (optional): Random seed for reproducible results
• output_format (optional): Output image format ("jpeg" or "png", default: "jpeg")
• steps (optional): Number of inference steps (1-50, flex only, default: 50)
• guidance (optional): Guidance scale (1.5-10, flex only, default: 4.5)

flux_edit

Edit existing images using FLUX.2 AI models.

Parameters:

• prompt (required): Text description of the edit to be applied
• input_image (required): Path to input image file (local) or image URL
• model (optional): FLUX.2 model to use ("pro" or "flex", default: "pro")
• reference_images (optional): Additional reference image files or URLs (max 7 for pro, 9 for flex)
• width (optional): Output width in pixels (multiple of 16, defaults to input dimension)
• height (optional): Output height in pixels (multiple of 16, defaults to input dimension)
• safety_tolerance (optional): Moderation level (0-5, default: 2)
• seed (optional): Random seed for reproducible results
• output_format (optional): Output image format ("jpeg" or "png", default: "jpeg")
• steps (optional): Number of inference steps (1-50, flex only, default: 50)
• guidance (optional): Guidance scale (1.5-10, flex only, default: 4.5)

Installation

Via npm (recommended)

# Install globally
npm install -g flux-bfl-mcp

# Or install locally
npm install flux-bfl-mcp

Via npx (for one-time use)

npx flux-bfl-mcp --help

From source

git clone https://github.com/Lunar-feedmob/Lunar_MCP_Project.git
cd Lunar_MCP_Project
cd flux-server  # Adjust path if different
npm install
npm run build

Configuration

1. Get BFL API Key

Visit Black Forest Labs to get your API key.

2. Configure MCP Server

For Claude Desktop

Add to your MCP configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "flux-bfl": {
      "command": "npx",
      "args": ["-y", "flux-bfl-mcp"],
      "env": {
        "BFL_API_KEY": "your-bfl-api-key-here"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

For other MCP clients (like Cline)

For Cline, add to: /home/codespace/.vscode-remote/data/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

{
  "mcpServers": {
    "flux-bfl": {
      "command": "npx",
      "args": ["-y", "flux-bfl-mcp"],
      "env": {
        "BFL_API_KEY": "your-bfl-api-key-here"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Usage Examples

Generate an Image

// Using the flux_generate tool
{
  "prompt": "A serene landscape with mountains and a lake at sunset",
  "width": 1024,
  "height": 768,
  "model": "pro"
}

Edit an Image

// Using the flux_edit tool
{
  "prompt": "Add a small boat on the lake and make the sky more dramatic",
  "input_image": "https://example.com/image.jpg",
  "model": "flex",
  "steps": 35,
  "guidance": 6.5
}

API Details

This server uses the Black Forest Labs FLUX.2 API. All parameters are passed through to the BFL API with appropriate validation:

• Pro Model: High-quality, fast generation
• Flex Model: More customizable with adjustable steps and guidance
• Dimensions: Must be multiples of 16 pixels
• Safety: 0 = most permissive, 5 = most restrictive

Development

# Install dependencies
npm install

# Build the server
npm run build

# Auto-build with watch mode
npm run watch

# Test with inspector
npm run inspector

Requirements

• Node.js 18+
• Valid BFL API key
• MCP-compatible client (Claude Desktop, Cline, etc.)

License

MIT - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Credits

Built with the Model Context Protocol SDK and uses the Black Forest Labs FLUX.2 API.