FluxMCP
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 modelsImage Editing - Edit existing images with context-aware Flux Kontext modelsTask Management - Track async generation tasks and batch status queriesModel Guide - Built-in model selection and prompt writing guidanceDual Transport - stdio (local) and HTTP (remote/cloud) modesDocker Ready - Containerized with K8s deployment manifestsSecure - Bearer token auth with per-request isolation in HTTP mode
Tool Description flux_generate_imageGenerate AI images from a text prompt using Flux. flux_edit_imageEdit an existing image using Flux with a text prompt. flux_list_modelsList all available Flux models and their capabilities. flux_list_actionsList all available Flux tools and their use cases. flux_get_taskQuery the status and result of a Flux image generation task. flux_get_tasks_batchQuery multiple Flux image generation tasks at once.
Quick Start
1. Get Your API Token
Sign up at AceDataCloud Platform
Go to the API documentation page
Click "Acquire" to get your API token
Copy the token for use below
2. Use the Hosted Server (Recommended)
AceDataCloud hosts a managed MCP server — no local installation required .
Endpoint: https://flux.mcp.acedata.cloud/mcp
All requests require a Bearer token. Use the API token from Step 1.
Claude.ai
Connect directly on Claude.ai with OAuth — no API token needed :
Go to Claude.ai Settings → Integrations → Add More
Enter the server URL: https://flux.mcp.acedata.cloud/mcp
Complete the OAuth login flow
Start using the tools in your conversation
Claude Desktop
Add to your config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers" : {
"flux" : {
"type" : "streamable-http" ,
"url" : "https://flux.mcp.acedata.cloud/mcp" ,
"headers" : {
"Authorization" : "Bearer YOUR_API_TOKEN"
}
}
}
}
Cursor / Windsurf
Add to your MCP config (.cursor/mcp.json or .windsurf/mcp.json):
{
"mcpServers" : {
"flux" : {
"type" : "streamable-http" ,
"url" : "https://flux.mcp.acedata.cloud/mcp" ,
"headers" : {
"Authorization" : "Bearer YOUR_API_TOKEN"
}
}
}
}
VS Code (Copilot)
Add to your VS Code MCP config (.vscode/mcp.json):
{
"servers" : {
"flux" : {
"type" : "streamable-http" ,
"url" : "https://flux.mcp.acedata.cloud/mcp" ,
"headers" : {
"Authorization" : "Bearer YOUR_API_TOKEN"
}
}
}
}
Or install the Ace Data Cloud MCP extension for VS Code, which registers the hosted MCP servers with one-click setup.
JetBrains IDEs
Go to Settings → Tools → AI Assistant → Model Context Protocol (MCP)
Click Add → HTTP
Paste:
{
"mcpServers" : {
"flux" : {
"url" : "https://flux.mcp.acedata.cloud/mcp" ,
"headers" : {
"Authorization" : "Bearer YOUR_API_TOKEN"
}
}
}
}
Claude Code
Claude Code supports MCP servers natively:
claude mcp add flux --transport http https://flux.mcp.acedata.cloud/mcp \
-h "Authorization: Bearer YOUR_API_TOKEN"
Or add to your project's .mcp.json:
{
"mcpServers" : {
"flux" : {
"type" : "streamable-http" ,
"url" : "https://flux.mcp.acedata.cloud/mcp" ,
"headers" : {
"Authorization" : "Bearer YOUR_API_TOKEN"
}
}
}
}
Cline
Add to Cline's MCP settings (.cline/mcp_settings.json):
{
"mcpServers" : {
"flux" : {
"type" : "streamable-http" ,
"url" : "https://flux.mcp.acedata.cloud/mcp" ,
"headers" : {
"Authorization" : "Bearer YOUR_API_TOKEN"
}
}
}
}
Amazon Q Developer
Add to your MCP configuration:
{
"mcpServers" : {
"flux" : {
"type" : "streamable-http" ,
"url" : "https://flux.mcp.acedata.cloud/mcp" ,
"headers" : {
"Authorization" : "Bearer YOUR_API_TOKEN"
}
}
}
}
Roo Code
Add to Roo Code MCP settings:
{
"mcpServers" : {
"flux" : {
"type" : "streamable-http" ,
"url" : "https://flux.mcp.acedata.cloud/mcp" ,
"headers" : {
"Authorization" : "Bearer YOUR_API_TOKEN"
}
}
}
}
Continue.dev
Add to .continue/config.yaml:
mcpServers:
- name: flux
type: streamable-http
url: https://flux.mcp.acedata.cloud/mcp
headers:
Authorization: "Bearer YOUR_API_TOKEN"
Zed
Add to Zed's settings (~/.config/zed/settings.json):
{
"language_models" : {
"mcp_servers" : {
"flux" : {
"url" : "https://flux.mcp.acedata.cloud/mcp" ,
"headers" : {
"Authorization" : "Bearer YOUR_API_TOKEN"
}
}
}
}
}
cURL Test
curl https://flux.mcp.acedata.cloud/health
curl -X POST https://flux.mcp.acedata.cloud/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
3. Or Run Locally (Alternative)
If you prefer to run the server on your own machine:
pip install mcp-flux-pro
uvx mcp-flux-pro
export ACEDATACLOUD_API_TOKEN="your_token_here"
mcp-flux-pro
mcp-flux-pro --transport http --port 8000
Claude Desktop (Local)
{
"mcpServers" : {
"flux" : {
"command" : "uvx" ,
"args" : [ "mcp-flux-pro" ] ,
"env" : {
"ACEDATACLOUD_API_TOKEN" : "your_token_here"
}
}
}
}
Docker (Self-Hosting)
docker pull ghcr.io/acedatacloud/mcp-flux-pro:latest
docker run -p 8000:8000 ghcr.io/acedatacloud/mcp-flux-pro:latest
Clients connect with their own Bearer token — the server extracts the token from each request's Authorization header.
Tool Description flux_generate_imageGenerate images from text prompts with model selection flux_edit_imageEdit existing images with text instructions flux_get_taskQuery status of a single generation task flux_get_tasks_batchQuery multiple task statuses at once flux_list_modelsList all available Flux models and capabilities flux_list_actionsShow all tools and workflow examples
Available Prompts
Prompt Description flux_image_generation_guideGuide for choosing the right tool and model flux_prompt_writing_guideBest practices for writing effective prompts flux_workflow_examplesCommon workflow patterns and examples
Supported Models
Model Quality Speed Size Format Best For flux-devGood Fast Pixels (256-1440px) Quick prototyping flux-proHigh Medium Pixels (256-1440px) Production use flux-kontext-proHigh Medium Aspect ratios Image editing flux-kontext-maxHighest Slower Aspect ratios Complex editing flux-2-flexHigh Fast Aspect ratios Flux 2 balanced quality flux-2-proHigher Medium Aspect ratios Flux 2 production flux-2-maxHighest Slower Aspect ratios Flux 2 maximum quality flux-2-kleinGood Fast Aspect ratios Flux 2 efficient output
Usage Examples
Generate an Image
"Generate a photorealistic mountain landscape at golden hour"
→ flux_generate_image(prompt="...", model="flux-2-max", size="16:9")
Edit an Image
"Add sunglasses to the person in this photo"
→ flux_edit_image(prompt="Add sunglasses", image_url="https://...", size="1:1", 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_TOKENYes (stdio) — API token from AceDataCloud ACEDATACLOUD_API_BASE_URLNo https://api.acedata.cloudAPI base URL ACEDATACLOUD_OAUTH_CLIENT_IDNo — OAuth client ID (hosted mode) ACEDATACLOUD_PLATFORM_BASE_URLNo https://platform.acedata.cloudPlatform base URL FLUX_REQUEST_TIMEOUTNo 1800Request timeout in seconds MCP_SERVER_NAMENo fluxMCP server name LOG_LEVELNo INFOLogging level
Development
Setup
git clone https://github.com/AceDataCloud/FluxMCP.git
cd FluxMCP
pip install -e ".[all]"
cp .env.example .env
ruff check .
ruff format .
mypy core tools main.py
Test
pytest --cov=core --cov=tools
pytest -m "not integration"
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 imagesPOST /flux/tasks — Query task status (single or batch)
Full API documentation: platform.acedata.cloud
Documentation
Documentation
License
MIT License — see LICENSE for details.
Links
FLUX 3 video
Use flux_generate_video with a structured request for t2v, i2v, v2v or draft_enhance. For example: {"mode":"t2v","prompt":"Waves at sunset","duration":5,"resolution":"hd","generate_audio":false}. Image mode requires keyframes; video mode requires start_video. Draft enhancement uses an owned platform draft_task_id and requires the temporary draft cache still to be available.
Video generation uses POST /flux/videos with action=generate (default) and mode=t2v/i2v/v2v/draft_enhance. Each generation mode accepts its own fields. Tools return task IDs asynchronously by default; use flux_get_task for the final video. Set async=false in the request to wait synchronously.
