FLUX MCP Server

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 — 列出带有使用说明的模型 1. 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/..."]
}

模型选择指南

安全

这个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