FLUX MCP Server

# FLUX MCP Server MCP server exposing [Replicate's FLUX](https://replicate.com/collections/flux) image generation models to Claude Desktop, Claude Code, and other MCP clients. ## Features - **6 FLUX models** via Replicate API: - **FLUX1.1 Pro Ultra** — highest quality text-to-image (up to ~4MP, raw realism mode) - **FLUX1.1 Pro** — fast, reliable commercial-grade default - **FLUX.1 Redux [dev]** — image variations/restyling - **FLUX.1 Fill [pro]** — professional inpainting/outpainting - **FLUX.1 Depth [dev]** — structure-preserving depth-guided editing - **FLUX.1 Canny [pro]** — edge-guided generation from sketches - **Two MCP tools**: 1. `flux_models` — list models with usage notes 2. `flux_generate` — generate images, save locally, return file paths + URLs ## Prerequisites - [Replicate API token](https://replicate.com/account/api-tokens) (required) - Node.js 18+ (for local development) ## Quick Start ### Claude Code **From local directory:** ```bash cd /path/to/flux-mcp-node claude mcp add --scope user flux-mcp --env REPLICATE_API_TOKEN=r8_your_token_here -- node /absolute/path/to/flux-mcp-node/index.js ``` **From npm (after publishing):** ```bash claude mcp add --scope user flux-mcp --env REPLICATE_API_TOKEN=r8_your_token_here -- npx flux-mcp@latest ``` ### Claude Desktop Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows): ```json { "mcpServers": { "flux-mcp": { "command": "npx", "args": ["flux-mcp@latest"], "env": { "REPLICATE_API_TOKEN": "r8_your_token_here" } } } } ``` **For local development:** ```json { "mcpServers": { "flux-mcp": { "command": "node", "args": ["/absolute/path/to/flux-mcp-node/index.js"], "env": { "REPLICATE_API_TOKEN": "r8_your_token_here" } } } } ``` Restart Claude Desktop. Get your Replicate API token from [replicate.com/account/api-tokens](https://replicate.com/account/api-tokens). ## Local Development ```bash git clone https://github.com/kmaurinjones/flux-mcp.git cd flux-mcp npm install export REPLICATE_API_TOKEN="r8_..." node index.js ``` ## Installation ### From npm (after publishing) ```bash npm install -g flux-mcp ``` ### From source ```bash git clone https://github.com/kmaurinjones/flux-mcp.git cd flux-mcp npm install npm link ``` ## Usage ### List available models Call `flux_models()` to see all supported models with usage notes. Returns: ```json [ { "model": "black-forest-labs/flux-1.1-pro-ultra", "display": "FLUX1.1 Pro Ultra", "kind": "text-to-image", "accepts_image": false, "notes": [ "Highest quality, up to ~4MP; 'raw' mode for realism.", "Use when you need best composition/large output." ], "key_inputs": ["prompt", "raw", "aspect_ratio", "seed", "output_quality", "go_fast"] } ] ``` ### Generate images #### Text-to-image (Pro) ``` Generate a mountain landscape (PNG by default): - prompt: "peaceful mountain landscape with snow-capped peaks and evergreen trees, golden hour" - download_path: "~/Pictures/flux-gen" - model: "black-forest-labs/flux-pro" - aspect_ratio: "16:9" ``` Or specify a different format: ``` Generate as JPEG: - prompt: "peaceful mountain landscape with snow-capped peaks and evergreen trees, golden hour" - download_path: "~/Pictures/flux-gen" - model: "black-forest-labs/flux-pro" - aspect_ratio: "16:9" - output_format: "jpeg" ``` #### Text-to-image (Ultra - highest quality) ``` Generate with maximum quality: - prompt: "sunlit minimalist living room, soft cream walls, terracotta accents" - download_path: "~/Pictures/flux-gen" - model: "black-forest-labs/flux-1.1-pro-ultra" - aspect_ratio: "16:9" - raw: true ``` #### Image variation (Redux) ``` Create variations of reference.png: - prompt: "keep composition, shift to sage/cream palette, add subtle grain" - download_path: "~/Pictures/flux-gen" - model: "black-forest-labs/flux-redux-dev" - image_path: "~/Pictures/reference.png" - num_outputs: 2 ``` #### Inpainting (Fill) ``` Remove objects from image: - prompt: "remove overhead wires, seamless sky" - download_path: "~/Pictures/flux-gen" - model: "black-forest-labs/flux-fill-pro" - image_path: "~/Pictures/street.jpg" - mask_path: "~/Pictures/street_mask.png" - guidance: 30 ``` ## Tool Reference ### `flux_models()` Returns list of available models with metadata, usage notes, and key input parameters. **Returns:** ```json [ { "model": "string", "display": "string", "kind": "string", "accepts_image": boolean, "notes": ["string"], "key_inputs": ["string"] } ] ``` ### `flux_generate(...)` Generate images and save to local disk. **Required parameters:** - `prompt` (string) — text prompt describing the image - `download_path` (string) — directory to save generated images **Optional parameters:** - `model` (string) — FLUX model to use (default: `flux-1.1-pro-ultra`) - `output_format` (string) — output image format: "png" (default), "jpeg", or "webp" - `image_path` (string) — local path or URL to input image (for models that accept images) - `mask_path` (string) — path/URL to mask image for inpainting (Fill model) - `aspect_ratio` (string) — e.g., "1:1", "16:9", "3:4" - `seed` (integer) — random seed for reproducibility - `raw` (boolean) — enable raw realism mode (Ultra model) - `num_outputs` (integer) — number of images to generate - `output_quality` (number) — quality setting (model-dependent) - `go_fast` (boolean) — speed vs quality tradeoff (model-dependent) - `strength` (number) — variation strength (Redux model) - `num_inference_steps` (integer) — inference steps (Fill model) - `guidance` (number) — guidance scale (Fill model) **Returns:** ```json { "model": "black-forest-labs/flux-pro", "saved": ["/absolute/path/to/file_1.webp"], "urls": ["https://replicate.delivery/..."] } ``` ## Model Selection Guide | Model | Use Case | Accepts Image | Speed | Quality | |-------|----------|---------------|-------|---------| | **FLUX1.1 Pro Ultra** | Best overall quality, large outputs, realism | No | Slower | Highest | | **FLUX1.1 Pro** | Fast reliable default, commercial use | No | Fast | High | | **FLUX.1 Redux [dev]** | Image variations, restyling | Yes | Fast | High | | **FLUX.1 Fill [pro]** | Inpainting, outpainting | Yes + Mask | Medium | High | | **FLUX.1 Depth [dev]** | Structure-preserving style transfer | Yes | Medium | High | | **FLUX.1 Canny [pro]** | Sketch-to-image, edge control | Yes | Medium | High | ## Security This MCP server implements multiple security measures: ### Path Traversal Protection - Download paths are validated and must be within: - User's home directory (`~`) - `/tmp` directory - Project's `downloads/` folder - Prevents writing files to arbitrary system locations ### URL Validation - Only HTTPS URLs allowed (no HTTP) - Downloaded images must come from `replicate.delivery` domain only - Prevents SSRF (Server-Side Request Forgery) attacks - Validates redirect targets ### Input Sanitization - Model IDs validated against allowlist - File paths normalized to prevent `../` attacks - Error messages sanitized to prevent information disclosure ### Error Handling - Sensitive information (stack traces, paths) not exposed to clients - Detailed errors logged server-side for debugging - User-friendly error messages returned ### Dependencies - Regular security audits via `npm audit` - Minimal dependency tree - Official MCP SDK and Replicate client only ## Troubleshooting **"REPLICATE_API_TOKEN is not set"** - Ensure the environment variable is exported or configured in your MCP client **"Model requires image_path"** - Redux, Fill, Depth, and Canny models require an input image - Provide `image_path` parameter with local file or URL **Images not downloading** - Check that `download_path` directory is writable - Verify you have sufficient disk space **"NSFW content detected"** - Replicate's safety filters blocked the content - Try rephrasing your prompt ## Development ### Running locally ```bash npm install export REPLICATE_API_TOKEN="r8_..." node index.js ``` ### Testing with MCP Inspector ```bash npm install -g @modelcontextprotocol/inspector mcp-inspector node index.js ``` ## Publishing to npm ```bash npm version patch # or minor, or major npm publish ``` ## License MIT ## Credits - [Replicate](https://replicate.com/) for FLUX model hosting - [Black Forest Labs](https://blackforestlabs.ai/) for FLUX models - [Model Context Protocol](https://modelcontextprotocol.io/) for the MCP SDK