{ "markdown": "# FluxMCP\n\n\n\n[![PyPI version](https://img.shields.io/pypi/v/mcp-flux-pro.svg)](https://pypi.org/project/mcp-flux-pro/)\n[![PyPI downloads](https://img.shields.io/pypi/dm/mcp-flux-pro.svg)](https://pypi.org/project/mcp-flux-pro/)\n[![CI](https://github.com/AceDataCloud/FluxMCP/actions/workflows/ci.yaml/badge.svg)](https://github.com/AceDataCloud/FluxMCP/actions/workflows/ci.yaml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n\nA [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for AI image generation and editing using [Flux](https://platform.acedata.cloud) through the [AceDataCloud](https://platform.acedata.cloud) platform.\n\nGenerate and edit stunning AI images with Flux models (flux-dev, flux-pro, flux-kontext) directly from Claude, Cursor, or any MCP-compatible client.\n\n## Features\n\n- **Image Generation** - Generate images from text prompts with 6 Flux models\n- **Image Editing** - Edit existing images with context-aware Flux Kontext models\n- **Task Management** - Track async generation tasks and batch status queries\n- **Model Guide** - Built-in model selection and prompt writing guidance\n- **Dual Transport** - stdio (local) and HTTP (remote/cloud) modes\n- **Docker Ready** - Containerized with K8s deployment manifests\n- **Secure** - Bearer token auth with per-request isolation in HTTP mode\n\n## Tool Reference\n\n| Tool | Description |\n|------|-------------|\n| `flux_generate_image` | Generate AI images from a text prompt using Flux. |\n| `flux_edit_image` | Edit an existing image using Flux with a text prompt. |\n| `flux_list_models` | List all available Flux models and their capabilities. |\n| `flux_list_actions` | List all available Flux tools and their use cases. |\n| `flux_get_task` | Query the status and result of a Flux image generation task. |\n| `flux_get_tasks_batch` | Query multiple Flux image generation tasks at once. |\n\n## Quick Start\n\n### 1. Get Your API Token\n\n1. Sign up at [AceDataCloud Platform](https://platform.acedata.cloud)\n2. Go to the [API documentation page](https://platform.acedata.cloud)\n3. Click **\"Acquire\"** to get your API token\n4. Copy the token for use below\n\n### 2. Use the Hosted Server (Recommended)\n\nAceDataCloud hosts a managed MCP server — **no local installation required**.\n\n**Endpoint:** `https://flux.mcp.acedata.cloud/mcp`\n\nAll requests require a Bearer token. Use the API token from Step 1.\n\n#### Claude.ai\n\nConnect directly on [Claude.ai](https://claude.ai) with OAuth — **no API token needed**:\n\n1. Go to Claude.ai **Settings → Integrations → Add More**\n2. Enter the server URL: `https://flux.mcp.acedata.cloud/mcp`\n3. Complete the OAuth login flow\n4. Start using the tools in your conversation\n\n#### Claude Desktop\n\nAdd to your config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n \"mcpServers\": {\n \"flux\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://flux.mcp.acedata.cloud/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer YOUR_API_TOKEN\"\n }\n }\n }\n}\n```\n\n#### Cursor / Windsurf\n\nAdd to your MCP config (`.cursor/mcp.json` or `.windsurf/mcp.json`):\n\n```json\n{\n \"mcpServers\": {\n \"flux\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://flux.mcp.acedata.cloud/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer YOUR_API_TOKEN\"\n }\n }\n }\n}\n```\n\n#### VS Code (Copilot)\n\nAdd to your VS Code MCP config (`.vscode/mcp.json`):\n\n```json\n{\n \"servers\": {\n \"flux\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://flux.mcp.acedata.cloud/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer YOUR_API_TOKEN\"\n }\n }\n }\n}\n```\n\nOr install the [Ace Data Cloud MCP extension](https://marketplace.visualstudio.com/items?itemName=acedatacloud.acedatacloud-mcp) for VS Code, which registers the hosted MCP servers with one-click setup.\n\n#### JetBrains IDEs\n\n1. Go to **Settings → Tools → AI Assistant → Model Context Protocol (MCP)**\n2. Click **Add** → **HTTP**\n3. Paste:\n\n```json\n{\n \"mcpServers\": {\n \"flux\": {\n \"url\": \"https://flux.mcp.acedata.cloud/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer YOUR_API_TOKEN\"\n }\n }\n }\n}\n```\n\n\n#### Claude Code\n\nClaude Code supports MCP servers natively:\n\n```bash\nclaude mcp add flux --transport http https://flux.mcp.acedata.cloud/mcp \\\n -h \"Authorization: Bearer YOUR_API_TOKEN\"\n```\n\nOr add to your project's `.mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"flux\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://flux.mcp.acedata.cloud/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer YOUR_API_TOKEN\"\n }\n }\n }\n}\n```\n\n#### Cline\n\nAdd to Cline's MCP settings (`.cline/mcp_settings.json`):\n\n```json\n{\n \"mcpServers\": {\n \"flux\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://flux.mcp.acedata.cloud/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer YOUR_API_TOKEN\"\n }\n }\n }\n}\n```\n\n#### Amazon Q Developer\n\nAdd to your MCP configuration:\n\n```json\n{\n \"mcpServers\": {\n \"flux\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://flux.mcp.acedata.cloud/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer YOUR_API_TOKEN\"\n }\n }\n }\n}\n```\n\n#### Roo Code\n\nAdd to Roo Code MCP settings:\n\n```json\n{\n \"mcpServers\": {\n \"flux\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://flux.mcp.acedata.cloud/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer YOUR_API_TOKEN\"\n }\n }\n }\n}\n```\n\n#### Continue.dev\n\nAdd to `.continue/config.yaml`:\n\n```yaml\nmcpServers:\n - name: flux\n type: streamable-http\n url: https://flux.mcp.acedata.cloud/mcp\n headers:\n Authorization: \"Bearer YOUR_API_TOKEN\"\n```\n\n#### Zed\n\nAdd to Zed's settings (`~/.config/zed/settings.json`):\n\n```json\n{\n \"language_models\": {\n \"mcp_servers\": {\n \"flux\": {\n \"url\": \"https://flux.mcp.acedata.cloud/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer YOUR_API_TOKEN\"\n }\n }\n }\n }\n}\n```\n\n#### cURL Test\n\n```bash\n# Health check (no auth required)\ncurl https://flux.mcp.acedata.cloud/health\n\n# MCP initialize\ncurl -X POST https://flux.mcp.acedata.cloud/mcp \\\n -H \"Content-Type: application/json\" \\\n -H \"Accept: application/json\" \\\n -H \"Authorization: Bearer YOUR_API_TOKEN\" \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}'\n```\n\n### 3. Or Run Locally (Alternative)\n\nIf you prefer to run the server on your own machine:\n\n```bash\n# Install from PyPI\npip install mcp-flux-pro\n# or\nuvx mcp-flux-pro\n\n# Set your API token\nexport ACEDATACLOUD_API_TOKEN=\"your_token_here\"\n\n# Run (stdio mode for Claude Desktop / local clients)\nmcp-flux-pro\n\n# Run (HTTP mode for remote access)\nmcp-flux-pro --transport http --port 8000\n```\n\n#### Claude Desktop (Local)\n\n```json\n{\n \"mcpServers\": {\n \"flux\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-flux-pro\"],\n \"env\": {\n \"ACEDATACLOUD_API_TOKEN\": \"your_token_here\"\n }\n }\n }\n}\n```\n\n#### Docker (Self-Hosting)\n\n```bash\ndocker pull ghcr.io/acedatacloud/mcp-flux-pro:latest\ndocker run -p 8000:8000 ghcr.io/acedatacloud/mcp-flux-pro:latest\n```\n\nClients connect with their own Bearer token — the server extracts the token from each request's `Authorization` header.\n\n## Available Tools\n\n| Tool | Description |\n| ---------------------- | ------------------------------------------------------ |\n| `flux_generate_image` | Generate images from text prompts with model selection |\n| `flux_edit_image` | Edit existing images with text instructions |\n| `flux_get_task` | Query status of a single generation task |\n| `flux_get_tasks_batch` | Query multiple task statuses at once |\n| `flux_list_models` | List all available Flux models and capabilities |\n| `flux_list_actions` | Show all tools and workflow examples |\n\n## Available Prompts\n\n| Prompt | Description |\n| ----------------------------- | -------------------------------------------- |\n| `flux_image_generation_guide` | Guide for choosing the right tool and model |\n| `flux_prompt_writing_guide` | Best practices for writing effective prompts |\n| `flux_workflow_examples` | Common workflow patterns and examples |\n\n## Supported Models\n\n| Model | Quality | Speed | Size Format | Best For |\n| ------------------ | ------- | ------ | ------------------- | ----------------------- |\n| `flux-dev` | Good | Fast | Pixels (256-1440px) | Quick prototyping |\n| `flux-pro` | High | Medium | Pixels (256-1440px) | Production use |\n| `flux-kontext-pro` | High | Medium | Aspect ratios | Image editing |\n| `flux-kontext-max` | Highest | Slower | Aspect ratios | Complex editing |\n| `flux-2-flex` | High | Fast | Aspect ratios | Flux 2 balanced quality |\n| `flux-2-pro` | Higher | Medium | Aspect ratios | Flux 2 production |\n| `flux-2-max` | Highest | Slower | Aspect ratios | Flux 2 maximum quality |\n| `flux-2-klein` | Good | Fast | Aspect ratios | Flux 2 efficient output |\n\n## Usage Examples\n\n### Generate an Image\n\n```\n\"Generate a photorealistic mountain landscape at golden hour\"\n→ flux_generate_image(prompt=\"...\", model=\"flux-2-max\", size=\"16:9\")\n```\n\n### Edit an Image\n\n```\n\"Add sunglasses to the person in this photo\"\n→ flux_edit_image(prompt=\"Add sunglasses\", image_url=\"https://...\", size=\"1:1\", model=\"flux-kontext-pro\")\n```\n\n### Check Task Status\n\n```\n\"What's the status of my generation?\"\n→ flux_get_task(task_id=\"...\")\n```\n\n## Environment Variables\n\n| Variable | Required | Default | Description |\n| --------------------------- | ----------- | --------------------------- | --------------------------- |\n| `ACEDATACLOUD_API_TOKEN` | Yes (stdio) | — | API token from AceDataCloud |\n| `ACEDATACLOUD_API_BASE_URL` | No | `https://api.acedata.cloud` | API base URL |\n| `ACEDATACLOUD_OAUTH_CLIENT_ID` | No | — | OAuth client ID (hosted mode) |\n| `ACEDATACLOUD_PLATFORM_BASE_URL` | No | `https://platform.acedata.cloud` | Platform base URL |\n| `FLUX_REQUEST_TIMEOUT` | No | `1800` | Request timeout in seconds |\n| `MCP_SERVER_NAME` | No | `flux` | MCP server name |\n| `LOG_LEVEL` | No | `INFO` | Logging level |\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/AceDataCloud/FluxMCP.git\ncd FluxMCP\npip install -e \".[all]\"\ncp .env.example .env\n# Edit .env with your API token\n```\n\n### Lint & Format\n\n```bash\nruff check .\nruff format .\nmypy core tools main.py\n```\n\n### Test\n\n```bash\n# Unit tests\npytest --cov=core --cov=tools\n\n# Skip integration tests\npytest -m \"not integration\"\n\n# With coverage report\npytest --cov=core --cov=tools --cov-report=html\n```\n\n### Git Hooks\n\n```bash\ngit config core.hooksPath .githooks\n```\n\n## API Reference\n\nThis MCP server uses the [AceDataCloud Flux API](https://platform.acedata.cloud):\n\n- **POST /flux/images** — Generate or edit images\n- **POST /flux/tasks** — Query task status (single or batch)\n\nFull API documentation: [platform.acedata.cloud](https://platform.acedata.cloud)\n\n## Documentation\n\n\n[Documentation](https://platform.acedata.cloud/documents/flux-mcp)\n\n## License\n\nMIT License — see [LICENSE](LICENSE) for details.\n\n## Links\n\n- [AceDataCloud Platform](https://platform.acedata.cloud)\n- [MCP Protocol](https://modelcontextprotocol.io/)\n- [Flux by Black Forest Labs](https://blackforestlabs.ai/)\n- [PyPI Package](https://pypi.org/project/mcp-flux-pro/)\n", "bytes": 12357, "sha": "1e75c0c0d553fa8ef33bf0fd2644c9a1b4c64f40794a2ce44eb4544436e4008b", "repo_slug": "acedatacloud/fluxmcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_acedatacloud_mcp_flux_pro_49ef34e9/readme" }