Flux MCP Integration Guide

MCP (Model Context Protocol) is a model context protocol launched by Anthropic, allowing AI models (such as Claude, GPT, etc.) to call external tools through standardized interfaces. Through the Flux MCP Server provided by WorldAi, you can directly generate and edit AI images in AI clients such as Claude Desktop, VS Code, and Cursor.

¶ Feature Overview

Flux MCP Server provides the following core features:

Text-to-image generation — Generate high-quality images through text prompts
Image editing — Edit existing images based on text instructions
Multi-model support — Supports multiple models such as Flux Pro, Flux Dev, Flux 2, Flux Kontext, and more
Model query — View all available models and their capabilities
Task query — Monitor generation progress and obtain results

¶ Prerequisites

Before use, you need to obtain an WorldAi API Token:

Register or log in to the WorldAi platform
Go to the Flux Images API page
Click "Acquire" to obtain an API Token (free credits are provided for the first application)

¶ Method 1: Use the Hosted MCP Server (Recommended, Zero Installation)

WorldAi has already hosted the Flux MCP Server in the cloud. No local dependencies need to be installed. You can use it directly by entering the URL below in your AI client:

https://flux.mcp.acedata.cloud/mcp

Authentication method: Simply add Authorization: Bearer your API Token to the request header (Claude.ai completes this automatically through OAuth, so there is no need to manually enter the Token).

Open Claude.ai → Customize in the lower-left corner → Connectors → Add More
Enter the following in the URL field: https://flux.mcp.acedata.cloud/mcp
Complete OAuth authorization login (automatically redirects to the WorldAi login page)
Return to the conversation interface, and the tools will be available

¶ Claude Desktop

Edit the configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "flux": {
      "type": "http",
      "url": "https://flux.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer 你的API Token"
      }
    }
  }
}

Save and restart Claude Desktop for the changes to take effect.

¶ Claude Code (Terminal Command Line)

claude mcp add flux --transport http https://flux.mcp.acedata.cloud/mcp \
  -H "Authorization: Bearer 你的API Token"

¶ VS Code (GitHub Copilot)

Create .vscode/mcp.json in the project root directory:

{
  "servers": {
    "flux": {
      "type": "http",
      "url": "https://flux.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer 你的API Token"
      }
    }
  }
}

¶ Cursor

Create .cursor/mcp.json in the project root directory:

{
  "mcpServers": {
    "flux": {
      "url": "https://flux.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer 你的API Token"
      }
    }
  }
}

¶ Other MCP-Supported Clients

Any client that supports the MCP Streamable HTTP protocol (such as Windsurf, Cline, ChatGPT Connectors, Gemini CLI, JetBrains AI Assistant, etc.) can connect by entering the following two items:

URL: https://flux.mcp.acedata.cloud/mcp
Header: Authorization: Bearer your API Token

¶ Method 2: Run Locally (pip / uvx Installation)

If you need to run offline, customize code, or deploy to an internal network, you can install the MCP Server locally and start it through stdio.

¶ Installation

Install with pip (recommended):

pip install mcp-flux-pro

Or install from source:

git clone https://github.com/AceDataCloud/FluxMCP.git
cd FluxMCP
pip install -e .

After installation is complete, you can use the mcp-flux-pro command to start the service.

¶ Use in Claude Desktop (Local)

Edit the Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following configuration:

{
  "mcpServers": {
    "flux": {
      "command": "mcp-flux-pro",
      "env": {
        "ACEDATACLOUD_API_TOKEN": "你的API Token"
      }
    }
  }
}

If using uvx (no need to install the package in advance):

{
  "mcpServers": {
    "flux": {
      "command": "uvx",
      "args": ["mcp-flux-pro"],
      "env": {
        "ACEDATACLOUD_API_TOKEN": "你的API Token"
      }
    }
  }
}

Save the configuration and restart Claude Desktop for the changes to take effect.

¶ Use in VS Code / Cursor (Local)

Create .vscode/mcp.json in the project root directory:

{
  "servers": {
    "flux": {
      "command": "mcp-flux-pro",
      "env": {
        "ACEDATACLOUD_API_TOKEN": "你的API Token"
      }
    }
  }
}

Or use uvx:

{
  "servers": {
    "flux": {
      "command": "uvx",
      "args": ["mcp-flux-pro"],
      "env": {
        "ACEDATACLOUD_API_TOKEN": "你的API Token"
      }
    }
  }
}

¶ Available Tools List

Tool Name	Description
`flux_generate_image`	Generate images through text prompts
`flux_edit_image`	Edit existing images based on text instructions
`flux_generate_video`	FLUX 3 text-to-video/image-to-video/video generation and enhancement of existing drafts
`flux_get_task`	Query the status of a single task
`flux_get_tasks_batch`	Query task statuses in batches
`flux_list_models`	List all available models and their capabilities
`flux_list_actions`	List all available tools and workflow examples

¶ Usage Examples

After configuration is complete, you can directly call these features using natural language in the AI client, for example:

"Help me generate a cyberpunk-style city night scene with Flux"
"Change the background of this photo to a beach"
"Use the Flux Kontext Pro model to edit this image and change the clothing color to red"
"List all available Flux models"

¶ More Information

GitHub repository: WorldAi/FluxMCP
PyPI package: mcp-flux-pro
API documentation: Flux Image Generation API

¶ Model and Size Constraints

flux-2-flex, flux-2-pro, flux-2-max, and Kontext models' size must use an aspect ratio, such as 1:1 or 16:9; pixel dimensions such as 1024x1024 cannot be used. flux-2-klein only supports generation and is not among the selectable models in flux_edit_image.

flux_generate_video distinguishes between t2v, i2v, v2v, and draft_enhance through request.mode, and inputs are displayed according to the mode. Draft enhancement must reference its own temporary draft_task_id. Submission is asynchronous by default; retain the returned task ID and use flux_get_task to retrieve the result.