Skip to main content
Glama
elhombrejd

BFL MCP Server

by elhombrejd
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript

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

Related MCP server: FLUX Image Generator MCP Server

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

  1. 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"
      }
    }
  }
}

  1. 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"
      }
    }
  }
}

  1. 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"
      }
    }
  }
}

  1. 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

Repository

🔗 GitHub: github.com/elhombrehd/bfl_mcp

Available Tools

2 tools
edit_imageB

Edit an existing image using FLUX.1 Kontext model based on a text prompt

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesText description of how to edit the image
input_imageYesBase64 encoded input image to edit
aspect_ratioNoAspect ratio of the output image (e.g., "1:1", "16:9", "9:16")1:1
seedNoSeed for reproducible generation
safety_toleranceNoSafety tolerance level (0-6)
output_formatNoOutput image formatjpeg

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the model ('FLUX.1 Kontext') but does not describe key behavioral traits such as whether the tool is read-only or destructive (implied as destructive since it edits images), authentication needs, rate limits, error handling, or output format details. The description is minimal and misses critical operational context for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded with the core action ('Edit an existing image') and includes essential context (model and prompt basis). Every part of the sentence contributes value, making it highly concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (editing images with multiple parameters) and lack of annotations and output schema, the description is incomplete. It does not cover behavioral aspects, output details (e.g., what is returned), error cases, or usage constraints. For a mutation tool with no structured safety or output information, the description should provide more context to be adequately helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all 6 parameters. The description does not add any parameter-specific information beyond what the schema provides (e.g., it doesn't explain prompt formatting, image encoding details, or safety tolerance implications). Baseline score of 3 is appropriate as the schema handles parameter documentation adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Edit') and resource ('an existing image'), specifying it uses the 'FLUX.1 Kontext model based on a text prompt'. It distinguishes from the sibling tool 'generate_image' by focusing on editing existing images rather than generating new ones, though it could be more explicit about the distinction. It's not a tautology and provides specific action details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for editing images with a text prompt, but does not explicitly state when to use this tool versus alternatives like 'generate_image'. It provides context (editing existing images) but lacks explicit guidance on exclusions or prerequisites, such as when not to use it or what alternatives exist beyond the sibling tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_imageC

Generate an image using FLUX.1 Kontext model based on a text prompt

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesText description of the image to generate
aspect_ratioNoAspect ratio of the image (e.g., "1:1", "16:9", "9:16")1:1
seedNoSeed for reproducible generation
safety_toleranceNoSafety tolerance level (0-6)
output_formatNoOutput image formatjpeg

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the model but doesn't cover critical aspects like rate limits, authentication requirements, potential costs, error conditions, or what the output looks like (e.g., image data format). For a generative tool with zero annotation coverage, this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded, with every element contributing essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of image generation, no annotations, and no output schema, the description is incomplete. It doesn't address behavioral traits, output format details, or usage context, making it inadequate for an agent to fully understand how to invoke this tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all 5 parameters. The description adds no additional parameter semantics beyond what's already in the schema (e.g., it doesn't explain prompt best practices or safety tolerance implications). Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('generate an image') and specifies the model ('FLUX.1 Kontext model'), which distinguishes it from generic image generation. However, it doesn't explicitly differentiate from the sibling 'edit_image' tool, which would require mentioning this is for creation from scratch rather than modification.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'edit_image'. It lacks context about appropriate scenarios, prerequisites, or exclusions, leaving the agent to infer usage based solely on the tool name and parameters.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updates
    • First observededit_image
    • First observedgenerate_image
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.1/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: 'edit_image' modifies an existing image, while 'generate_image' creates a new image from scratch. There is no overlap in functionality, making it impossible for an agent to confuse them.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern ('edit_image' and 'generate_image'), using the same naming convention and style. The verbs are distinct and appropriately descriptive for their actions.

Tool Count2/5

With only two tools, the server feels thin for an image generation/editing domain. It lacks essential operations like retrieving, listing, or deleting images, and does not cover a complete workflow, making it under-scoped for typical use cases.

Completeness2/5

The tool surface is severely incomplete for an image-related server. It includes generation and editing but misses critical operations such as retrieving, listing, managing, or deleting images, leaving significant gaps that will hinder agent functionality.

Resources

Related MCP Connectors

Related MCP Servers