BFL MCP Server

Model Context Protocol (MCP) server for Black Forest Labs FLUX image generation and editing using FLUX.1 Kontext Pro.

🎨 Create and edit images with AI using natural language through the MCP protocol

Features

• 🎨 Image Generation: Generate high-quality images from text prompts using FLUX.1 Kontext Pro
• ✏️ Image Editing: Edit existing images with natural language instructions
• 🚀 Easy Installation: Run directly with npx - no local setup required
• 🔧 Configurable: Support for aspect ratios, seeds, safety settings, and output formats
• 🔗 MCP Compatible: Works with Claude Desktop, Claude Code, and other MCP clients

Installation & Usage

Quick Start with npx

# Run the MCP server with your BFL API key
npx bfl-mcp-server YOUR_BFL_API_KEY

Environment Variable

# Set environment variable
export BFL_API_KEY="your-api-key-here"
npx bfl-mcp-server

IDE Integration

Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "bfl": {
      "command": "npx",
      "args": ["bfl-mcp-server"],
      "env": {
        "BFL_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code

1. Via CLI Wizard (Recommended):

claude mcp add bfl-server -e BFL_API_KEY=your-api-key-here -- npx bfl-mcp-server

2. Via .claude.json (Project-specific): Create or edit .claude.json in your project root:

{
  "mcpServers": {
    "bfl": {
      "command": "npx",
      "args": ["bfl-mcp-server"],
      "env": {
        "BFL_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. Using Environment Variables:

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

Cursor IDE

1. Enable MCP: Go to Settings > Cursor Settings > MCP Servers and enable it

2. Project Configuration: Create .cursor/mcp.json in your project:

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

3. Global Configuration: Create ~/.cursor/mcp.json for system-wide access:

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

Windsurf IDE

1. Via Plugin Store:

   • Open Windsurf and navigate to Cascade assistant
   • Click the Plugins icon in the top right menu
   • Add custom server with our package

2. Manual Configuration:

   • Click the hammer (MCP) icon in Cascade
   • Click "Configure" to open ~/.codeium/windsurf/mcp_config.json
   • Add configuration:

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

3. Reload: Save and click "Refresh" in the Cascade assistant

Available Tools

generate_image

Generate an image from a text prompt.

Parameters:

• prompt (required): Text description of the image to generate
• aspect_ratio (optional): Image aspect ratio (default: "1:1")
  • Supported: "1:1", "16:9", "9:16", "4:3", "3:4", etc.
• seed (optional): Seed for reproducible generation
• safety_tolerance (optional): Safety level 0-6 (higher = more permissive)
• output_format (optional): "jpeg" or "png" (default: "jpeg")

Example:

{
  "name": "generate_image",
  "arguments": {
    "prompt": "A beautiful sunset over mountains with a lake reflection",
    "aspect_ratio": "16:9",
    "output_format": "jpeg"
  }
}

edit_image

Edit an existing image using natural language instructions.

Parameters:

• prompt (required): Text description of how to edit the image
• input_image (required): Base64 encoded input image
• aspect_ratio (optional): Output image aspect ratio (default: "1:1")
• seed (optional): Seed for reproducible generation
• safety_tolerance (optional): Safety level 0-6
• output_format (optional): "jpeg" or "png" (default: "jpeg")

Example:

{
  "name": "edit_image",
  "arguments": {
    "prompt": "Change the sky to be stormy with dark clouds",
    "input_image": "base64-encoded-image-data",
    "aspect_ratio": "16:9"
  }
}

Verification & Troubleshooting

Verify Installation

After configuring in any IDE, you should see:

• Claude Desktop: MCP tools available in chat
• Claude Code: Run /mcp command to check status
• Cursor: Green dot with tools list in MCP section
• Windsurf: Tools available in Cascade assistant

Common Issues

1. "Command not found": Ensure npx is installed (npm install -g npm)
2. "Permission denied": Try with sudo or check Node.js permissions
3. "API key invalid": Verify your BFL API key at bfl.ai
4. "Server not starting": Check IDE logs for detailed error messages

Testing the Server

Test manually before IDE integration:

# Test the server directly
npx bfl-mcp-server your-api-key

# Should show: "BFL MCP Server running on stdio"

API Key

Get your API key from Black Forest Labs.

Technical Details

• Model: FLUX.1 Kontext Pro
• Output: ~1MP images (1024x1024 for 1:1 ratio)
• URL Validity: Generated image URLs are valid for 10 minutes
• Processing: Asynchronous with automatic polling
• Timeout: 5 minutes maximum generation time

Development

Local Development

# Clone and install
git clone https://github.com/elhombrehd/bfl_mcp.git
cd bfl_mcp
npm install

# Build
npm run build

# Test with API key
BFL_API_KEY="your-key" npm run dev

Testing

# Run API tests
node test.js

Author

Created by @elhombrehd

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

• Issues: GitHub Issues
• BFL API Documentation: docs.bfl.ai
• MCP Protocol: Model Context Protocol

Repository

🔗 GitHub: github.com/elhombrehd/bfl_mcp