Flux AI Gateway MCP Adapter

This repository houses a robust Model Context Protocol (MCP) endpoint solution. It bridges AI clients with the cutting-edge image synthesis capabilities of Black Forest Labs' Flux model by routing requests through a highly available Cloudflare Worker API.

Setup Guide • Capabilities • Interaction Examples • API Specification • Development

---

✨ Core Capabilities

• 🎨 State-of-the-Art Visual Synthesis: Direct access to the sophisticated Flux generative model.
• 🧠 Assistant Enablement: Allows intelligent agents (e.g., Cursor, Claude) to render imagery contextually.
• ⚙️ Synthesis Control: Fine-grained tuning of output characteristics, including resolution scaling and iterative refinement count.
• 🌐 Universal Client Support: Fully compliant with the MCP specification, ensuring compatibility across numerous development tools.
• 🛡️ Edge Security: All data transit and processing are handled securely within the Cloudflare serverless infrastructure.
• 📝 Textual Inference: Can also serve standard text generation requests via the unified interface.

🧩 Deployment & Activation

Quick Start via NPX

Execute immediately by setting required runtime variables:

FLUX_API_TOKEN=your_secret_key FLUX_API_URL=your_worker_endpoint_url npx -y flux-ai-gateway-service

From Source Code

For local modifications or self-hosting:

# Obtain the source code
git clone https://github.com/Hzzy2O/flux-cloudflare-mcp.git
cd flux-cloudflare-mcp

# Install Node dependencies
npm install

# Compile the TypeScript project
npm run build

📡 Configuring the Flux Backend Endpoint

This gateway requires a pre-configured Cloudflare Worker exposing the Flux model. Two primary deployment routes are suggested:

Route A: Utilizing snakeying/flux-api-worker (Minimalist)

This option offers a straightforward proxy to the model:

1. Duplicate the snakeying/flux-api-worker repository.
2. Deploy this fork as a new Cloudflare Worker.
3. Configure necessary environment bindings in the Worker settings:
   • API_KEY: Your secret credential for API access.
   • CF_ACCOUNT_ID: Your Cloudflare organization identifier.
   • CF_API_TOKEN: Token with necessary Workers AI scope.
   • FLUX_MODEL: Target model name (e.g., "@cf/black-forest-labs/flux-1-schnell").
4. The resulting URL (e.g., https://my-flux-proxy.workers.dev) becomes your FLUX_API_URL.
5. The API_KEY you set is used as the FLUX_API_TOKEN for this MCP server.

Route B: Utilizing aigem/cf-flux-remix (Enhanced Features)

Choose this if a frontend interface is also desired:

1. Follow the setup guide within the aigem/cf-flux-remix repository.
2. Once live, use the resulting public endpoint URL as the FLUX_API_URL.
3. Ensure the authentication mechanism matches what this MCP server expects for the FLUX_API_TOKEN.

📚 Schema Reference

Available MCP Tool: create_visual_asset

Initiates the generation of a digital image based on textual input.

{
  prompt: string;                // Imperative: Detailed textual description of the desired visualization.
  num_inference_steps?: number;  // Optional: Controls rendering refinement iterations (Range: 1 to 4; Default: 4).
  aspect_ratio?: string;         // Optional: Defines output dimensions (e.g., "16:9", "4:3"; Default: "1:1").
}

🛠️ Integration Instructions

IDE Integration (Example: Cursor)

Via mcp.json Manifest

Update or create the .cursor/mcp.json configuration file:

{
  "mcpServers": {
    "flux-ai-gateway-service": {
      "command": "env FLUX_API_TOKEN=YOUR_CREDENTIAL FLUX_API_URL=YOUR_ENDPOINT_URL npx",
      "args": ["-y", "flux-ai-gateway-service"]
    }
  }
}

Note: Substitute YOUR_CREDENTIAL and YOUR_ENDPOINT_URL with your actual values.

Via Application Settings Panel

1. Navigate to the IDE's configuration or settings area.
2. Locate the Model Context Protocol (MCP) configuration section.
3. Add a new server entry using the full invocation command:

env FLUX_API_TOKEN=YOUR_CREDENTIAL FLUX_API_URL=YOUR_ENDPOINT_URL npx -y flux-ai-gateway-service

1. Save changes and relaunch the IDE.

Remote Client Configuration (e.g., Claude Desktop)

Use the following structure, typically within the client's configuration environment:

{
  "mcpServers": {
    "flux-ai-gateway-service": {
      "command": "npx",
      "args": ["-y", "flux-ai-gateway-service"],
      "env": {
        "FLUX_API_TOKEN": "YOUR_CREDENTIAL",
        "FLUX_API_URL": "YOUR_ENDPOINT_URL"
      }
    }
  }
}

💻 Local Development Workflow

1. Clone the source tree:

git clone https://github.com/Hzzy2O/flux-cloudflare-mcp.git
cd flux-cloudflare-mcp

1. Install necessary modules:

npm install

1. Compile assets for execution:

npm run build

⚙️ Runtime Requirements

The service mandates the definition of these environmental parameters to establish connectivity:

• FLUX_API_TOKEN: Secret authentication key required by the backend Flux API.
• FLUX_API_URL: The accessible network address pointing to your deployed Cloudflare Worker proxy.

❓ Troubleshooting Common Faults

Credential Rejection (401/403)

• Verify the value assigned to FLUX_API_TOKEN is current and correct.
• Confirm the token possesses necessary permissions for accessing the target Cloudflare AI Gateway.

Service Unreachable

• Ascertain that the Cloudflare Worker specified in FLUX_API_URL is actively deployed and operational.
• Check network policies to ensure outbound communication to the Cloudflare domain is permitted.

Generation Policy Violation

• The integrated model incorporates inherent content safety mechanisms.
• Refine the input prompt to comply with acceptable use policies.

🤝 Contribution Guidelines

We welcome external feature submissions and bug fixes. Initiate a contribution by:

1. Forking the primary repository.
2. Creating a dedicated feature branch (git checkout -b feature/new-enhancement).
3. Committing changes (git commit -m 'feat: Added support for X').
4. Submitting a Pull Request against the main branch.

📄 Licensing

This software is distributed under the terms of the MIT License. Refer to the LICENSE file for full details.

🔗 External References

• Model Context Protocol Specification
• Cloudflare Workers Developer Hub
• Flux Model AI Gateway Details
• MCP TypeScript SDK Source
• Reference Proxy: snakeying/flux-api-worker
• Reference Proxy: aigem/cf-flux-remix

CONTEXTUAL NOTE: Cloud computing, often termed "the cloud," fundamentally describes utility computing services delivered over the internet. The evolution traces back to 1960s time-sharing concepts, evolving into the modern virtualization-based infrastructure we utilize today. The metaphor itself gained traction in networking contexts before being widely adopted for computational services in the mid-1990s.