MCP Flux

A Model Context Protocol (MCP) server for AI image generation and editing using Flux through the AceDataCloud platform.

Generate and edit stunning AI images with Flux models (flux-dev, flux-pro, flux-kontext) directly from Claude, Cursor, or any MCP-compatible client.

Features

• 🎨 Image Generation — Generate images from text prompts with 6 Flux models
• ✏️ Image Editing — Edit existing images with context-aware Flux Kontext models
• 🔄 Task Management — Track async generation tasks and batch status queries
• 📋 Model Guide — Built-in model selection and prompt writing guidance
• 🌐 Dual Transport — stdio (local) and HTTP (remote/cloud) modes
• 🐳 Docker Ready — Containerized with K8s deployment manifests
• 🔒 Secure — Bearer token auth with per-request isolation in HTTP mode

Quick Start

Install from PyPI

pip install mcp-flux-pro

Configure API Token

Get your API token from AceDataCloud Platform:

export ACEDATACLOUD_API_TOKEN="your_api_token_here"

Run the Server

# stdio mode (for Claude Desktop, Cursor, etc.)
mcp-flux-pro

# HTTP mode (for remote/cloud deployment)
mcp-flux-pro --transport http --port 8000

Claude Desktop Integration

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "flux": {
      "command": "mcp-flux-pro",
      "env": {
        "ACEDATACLOUD_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Or using uvx (no install required):

{
  "mcpServers": {
    "flux": {
      "command": "uvx",
      "args": ["mcp-flux-pro"],
      "env": {
        "ACEDATACLOUD_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Cursor Integration

Add to your Cursor MCP configuration (.cursor/mcp.json):

{
  "mcpServers": {
    "flux": {
      "command": "mcp-flux-pro",
      "env": {
        "ACEDATACLOUD_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Remote HTTP Mode

For cloud deployment or shared servers:

mcp-flux-pro --transport http --port 8000

Connect from clients using the HTTP endpoint:

{
  "mcpServers": {
    "flux": {
      "url": "https://flux.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer your_api_token_here"
      }
    }
  }
}

Docker

# Build
docker build -t mcp-flux .

# Run
docker run -p 8000:8000 mcp-flux

Or using Docker Compose:

docker compose up --build

Available Tools

Tool	Description
flux_generate_image	Generate images from text prompts with model selection
flux_edit_image	Edit existing images with text instructions
flux_get_task	Query status of a single generation task
flux_get_tasks_batch	Query multiple task statuses at once
flux_list_models	List all available Flux models and capabilities
flux_list_actions	Show all tools and workflow examples

Available Prompts

Prompt	Description
flux_image_generation_guide	Guide for choosing the right tool and model
flux_prompt_writing_guide	Best practices for writing effective prompts
flux_workflow_examples	Common workflow patterns and examples

Supported Models

Model	Quality	Speed	Size Format	Best For
flux-dev	Good	Fast	Pixels (256-1440px)	Quick prototyping
flux-pro	High	Medium	Pixels (256-1440px)	Production use
flux-pro-1.1	High	Medium	Pixels (256-1440px)	Better prompt following
flux-pro-1.1-ultra	Highest	Slower	Aspect ratios	Maximum quality
flux-kontext-pro	High	Medium	Aspect ratios	Image editing
flux-kontext-max	Highest	Slower	Aspect ratios	Complex editing

Usage Examples

Generate an Image

"Generate a photorealistic mountain landscape at golden hour"
→ flux_generate_image(prompt="...", model="flux-pro-1.1-ultra", size="16:9")

Edit an Image

"Add sunglasses to the person in this photo"
→ flux_edit_image(prompt="Add sunglasses", image_url="https://...", model="flux-kontext-pro")

Check Task Status

"What's the status of my generation?"
→ flux_get_task(task_id="...")

Environment Variables

Variable	Required	Default	Description
ACEDATACLOUD_API_TOKEN	Yes (stdio)	—	API token from AceDataCloud
ACEDATACLOUD_API_BASE_URL	No	https://api.acedata.cloud	API base URL
FLUX_REQUEST_TIMEOUT	No	1800	Request timeout in seconds
MCP_SERVER_NAME	No	flux	MCP server name
LOG_LEVEL	No	INFO	Logging level

Development

Setup

git clone https://github.com/AceDataCloud/MCPFlux.git
cd MCPFlux
pip install -e ".[all]"
cp .env.example .env
# Edit .env with your API token

Lint & Format

ruff check .
ruff format .
mypy core tools main.py

Test

# Unit tests
pytest --cov=core --cov=tools

# Skip integration tests
pytest -m "not integration"

# With coverage report
pytest --cov=core --cov=tools --cov-report=html

Git Hooks

git config core.hooksPath .githooks

API Reference

This MCP server uses the AceDataCloud Flux API:

• POST /flux/images — Generate or edit images
• POST /flux/tasks — Query task status (single or batch)

Full API documentation: platform.acedata.cloud

License

MIT License — see LICENSE for details.

Links

• AceDataCloud Platform
• MCP Protocol
• Flux by Black Forest Labs
• PyPI Package