使用说明

FLUX MCP 服务器

MCP服务器暴露 Replicate的FLUX 将图像生成模型集成到Claude Desktop、Claude Code及其他MCP客户端中。

特点/特性

6个FLUX模型 通过Replicate API：
- FLUX1.1 Pro Ultra — 最高品质的文本到图像生成（高达约4MP，原始真实模式）
- FLUX1.1 Pro — 快速、可靠的商用级默认设置
- FLUX.1 Redux [开发版] — 图像变化/重新设计
- FLUX.1 Fill [专业版] — 专业图像修复/扩展
- FLUX.1 深度 [开发版] — 保持结构的深度引导编辑
- FLUX.1 Canny [专业版] — 从草图中进行边缘引导生成
两个MCP工具：
1. flux_models — 列出带有使用说明的模型
2. flux_generate — 生成图像，保存到本地，返回文件路径 + URL

先决条件

复制API令牌（必需）
Node.js 18+（用于本地开发）

快速入门

克劳德·科德

从本地目录：

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

从 npm（发布后）：

claude mcp add --scope user flux-mcp --env REPLICATE_API_TOKEN=r8_your_token_here -- npx flux-mcp@latest

Claude Desktop（可译为“Claude桌面版”或保持原名，根据上下文判断是否需要意译）

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows): （可译为）（针对Windows系统）：

{
  "mcpServers": {
    "flux-mcp": {
      "command": "npx",
      "args": ["flux-mcp@latest"],
      "env": {
        "REPLICATE_API_TOKEN": "r8_your_token_here"
      }
    }
  }
}

对于本地开发：

{
  "mcpServers": {
    "flux-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/flux-mcp-node/index.js"],
      "env": {
        "REPLICATE_API_TOKEN": "r8_your_token_here"
      }
    }
  }
}

重启Claude桌面版。从以下位置获取您的Replicate API密钥： replicate.com/account/api-tokens（中文可译为：“replicate.com账户/API令牌页面”）。

本地开发

git clone https://github.com/kmaurinjones/flux-mcp.git
cd flux-mcp
npm install
export REPLICATE_API_TOKEN="r8_..."
node index.js

安装

从 npm（发布后）

npm install -g flux-mcp

来自源头

git clone https://github.com/kmaurinjones/flux-mcp.git
cd flux-mcp
npm install
npm link

使用

列出可用模型

呼叫 flux_models() 查看所有支持的模型及其使用说明。

返回值：

[
  {
    "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 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"

或者指定不同的格式：

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"

文本到图像（Ultra - 最高品质）

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

图像变化（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

图像修复（填充）

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

工具参考

`flux_models()`

返回可用模型的列表，包含元数据、使用说明和关键输入参数。

返回：

[
  {
    "model": "string",
    "display": "string",
    "kind": "string",
    "accepts_image": boolean,
    "notes": ["string"],
    "key_inputs": ["string"]
  }
]

`flux_generate(...)`

生成图像并保存到本地磁盘。

必需参数：

prompt (字符串) — 描述图像的文本提示
download_path （字符串）— 保存生成图像的目录

可选参数：

model (字符串) — 要使用的FLUX模型（默认： flux-1.1-pro-ultra）
output_format (字符串) — 输出图像格式：“png”（默认）、“jpeg”或“webp”
image_path （字符串）— 输入图像的本地路径或URL（对于接受图像的模型）
mask_path (字符串) —— 用于修复（填充模型）的遮罩图像的路径/URL
aspect_ratio (字符串) — 例如，“1:1”，“16:9”，“3:4”
seed （整数）— 用于可重复性的随机种子
raw (boolean) — 启用原始真实模式（超模）
num_outputs （整数）— 要生成的图像数量
output_quality （数字）— 质量设置（取决于模型）
go_fast (布尔值) — 速度与质量之间的权衡（取决于模型）
strength （数字）— 变化强度（Redux 模型）
num_inference_steps (整数) — 推理步骤（填充模型）
guidance (数字) — 指导比例尺（填充模型）

返回：

{
  "model": "black-forest-labs/flux-pro",
  "saved": ["/absolute/path/to/file_1.webp"],
  "urls": ["https://replicate.delivery/..."]
}

模型选择指南

模型	使用场景	接受图像	速度	质量
FLUX1.1 Pro Ultra（可译为“FLUX1.1专业版超极”或根据具体语境简化为“FLUX1.1 Pro Ultra版”）	综合质量最佳，输出量大，逼真度高	否	速度较慢	最高
FLUX1.1 Pro	快速可靠的默认设置，商业用途	否	快速	高
FLUX.1 Redux [开发版]	图片变体，重新设计	是	快速	高
FLUX.1 Fill [专业版]	修复（Inpainting）、扩展（Outpainting）	是 + 掩码	中等	高
FLUX.1 深度 [开发版]	保持结构的风格迁移	是	中等	高
FLUX.1 Canny [专业版]	从草图到图像，边缘控制	是	中等	高

安全

这个MCP服务器实现了多项安全措施：

路径遍历保护

下载路径已验证，且必须位于以下范围内：
- 用户的主目录（~)
- /tmp 目录
- 项目的 downloads/ 文件夹
防止将文件写入任意系统位置

URL验证

仅允许HTTPS网址（不支持HTTP）
下载的图像必须来源于 replicate.delivery 仅域名
防止SSRF（服务器端请求伪造）攻击
验证重定向目标

输入净化（或输入验证与清理）

模型ID已与白名单进行验证
文件路径已规范化以防止 ../ 袭击；攻击
错误信息已进行清理，以防止信息泄露

错误处理

敏感信息（堆栈跟踪、路径）不暴露给客户端
服务器端详细记录错误以便调试
返回的用户友好型错误信息

依赖项

通过定期进行安全审计 npm audit
最小依赖树
仅官方MCP SDK和Replicate客户端

故障排除

REPLICATE_API_TOKEN 未设置

确保环境变量已在您的MCP客户端中导出或配置

“模型需要图像路径”

Redux、Fill、Depth 和 Canny 模型需要输入图像
提供 image_path 带有本地文件或URL的参数

图片无法下载

检查一下 download_path 目录可写
确认您有足够的磁盘空间

检测到“不适宜工作场合（NSFW）内容”

Replicate的安全过滤器屏蔽了内容
尝试重新措辞你的提示

发展

在本地运行

npm install
export REPLICATE_API_TOKEN="r8_..."
node index.js

使用MCP Inspector进行测试

npm install -g @modelcontextprotocol/inspector
mcp-inspector node index.js

发布到npm

npm version patch  # or minor, or major
npm publish

许可证

麻省理工学院（MIT）

致谢/鸣谢

复制用于FLUX模型托管
黑森林实验室用于FLUX模型
模型上下文协议用于MCP SDK