Replicate Flux MCP

Replicate Flux MCP

English | 中文

Replicate Flux MCP 是一款先进的 Model Context Protocol（MCP）服务，可帮助 AI 助手生成高质量图像和矢量图形。默认情况下，它使用 black-forest-labs/flux-schnell 生成栅格图像，并使用 recraft-ai/recraft-v3-svg 输出 SVG。你可以通过环境变量覆盖精选的图像/SVG 模型，图像工具也支持在每次调用时通过内置允许列表中的 model_id 覆盖模型。

📑 目录

• 快速开始与集成
  • 设置流程
  • Cursor 集成
  • Claude Desktop 集成
  • Smithery 集成
• Glama.ai 集成
• Codex 集成
• 功能
• 文档
  • 可用工具
  • 可用资源
  • 可用提示词
  • 结构化输出
  • 环境变量
• 开发
  • 测试
• 技术详情
• 故障排除
• 贡献
• 许可证
• 资源
• 示例

🚀 快速开始与集成

设置流程

1. 获取 Replicate API 令牌

   • 在 Replicate 注册
   • 在账户设置中创建 API 令牌

2. 选择集成方式

   • 根据你偏好的 MCP 客户端，选择以下一种集成方式

3. 让 AI 助手生成图像

   • 直接自然地提问：“你能生成一张日落时分宁静的山景图吗？”
   • 或者描述得更具体：“请创建一张宁静的山景图，前景中有一片湖泊映照着日落的色彩。”

4. 探索高级功能

   • 尝试不同的参数设置，以自定义生成结果
   • 使用 generate_svg 尝试生成 SVG
   • 使用批量图像生成或变体生成功能

Cursor 集成

方法 1：使用 mcp.json

1. 在项目目录中创建或编辑 .cursor/mcp.json 文件：

{
  "mcpServers": {
    "replicate-flux-mcp": {
      "command": "env REPLICATE_API_TOKEN=YOUR_TOKEN npx",
      "args": ["-y", "replicate-flux-mcp"]
    }
  }
}

2. 将 YOUR_TOKEN 替换为你的 Replicate API 令牌
3. 重启 Cursor 以应用更改

方法 2：手动模式

1. 打开 Cursor 并进入设置
2. 前往“MCP”或“Model Context Protocol”部分
3. 点击“Add Server”或相应选项
4. 在相应字段中输入以下命令：

env REPLICATE_API_TOKEN=YOUR_TOKEN npx -y replicate-flux-mcp

5. 将 YOUR_TOKEN 替换为你的 Replicate API 令牌
6. 保存设置，必要时重启 Cursor

Claude Desktop 集成

1. 在配置目录中创建或编辑 mcp.json 文件：

{
  "mcpServers": {
    "replicate-flux-mcp": {
      "command": "npx",
      "args": ["-y", "replicate-flux-mcp"],
      "env": {
        "REPLICATE_API_TOKEN": "YOUR TOKEN"
      }
    }
  }
}

2. 将 YOUR_TOKEN 替换为你实际的 Replicate API 令牌
3. 重启 Claude Desktop 以应用更改

Smithery 集成

此 MCP 服务在 Smithery 上提供托管服务，无需自行设置服务即可使用。

1. 访问 Smithery；如果还没有账号，请创建一个
2. 前往 Replicate Flux MCP 服务页面
3. 点击“Add to Workspace”，将服务添加到你的 Smithery 工作区
4. 配置你的 MCP 客户端（Cursor、Claude Desktop 等）以使用你的 Smithery 工作区 URL

如需了解如何在 MCP 客户端中使用 Smithery，请访问 Smithery 文档。

Glama.ai 集成

此 MCP 服务也在 Glama.ai 上提供托管服务，让你无需本地设置即可使用。

1. 访问 Glama.ai；如果还没有账号，请创建一个
2. 前往 Replicate Flux MCP 服务页面
3. 点击“Install Server”，将服务添加到你的工作区
4. 配置你的 MCP 客户端以使用你的 Glama.ai 工作区

如需了解详情，请访问 Glama.ai MCP 服务文档。

Codex 集成

将服务添加到 ~/.codex/config.toml：

[mcp_servers.replicate]
command = "npx"
args = ["-y", "replicate-flux-mcp"]
env = { REPLICATE_API_TOKEN = "your-replicate-api-token", REPLICATE_IMAGE_MODEL_ID = "your-image-model-id", REPLICATE_SVG_MODEL_ID = "your-svg-model-id" }
startup_timeout_sec = 30_000

按需替换环境变量值。如果省略 REPLICATE_IMAGE_MODEL_ID / REPLICATE_SVG_MODEL_ID，服务将分别为图像和 SVG 使用 black-forest-labs/flux-schnell 和 recraft-ai/recraft-v3-svg。

精选工具会根据内置允许列表验证模型覆盖项：

• 图像生成：black-forest-labs/flux-schnell、google/imagen-4、black-forest-labs/flux-kontext-pro、ideogram-ai/ideogram-v3-turbo、black-forest-labs/flux-1.1-pro、black-forest-labs/flux-dev
• SVG 生成：recraft-ai/recraft-v3-svg
• 旧版 run_model 额外模型：minimax/video-01、luma/reframe-video、topazlabs/video-upscale、topazlabs/image-upscale、szcho/codeformer、tencentarc/gfpgan

🌟 功能

• 🖼️ 高质量图像生成 — 默认使用 Flux Schnell 生成栅格图像，并支持通过环境变量和按工具指定图像模型覆盖项。
• 🎨 矢量图形 — 使用 Recraft V3 SVG 创建徽标、图标和图表。
• 📊 批量生成 + 多个变体 — 根据 N 个提示词生成 N 张图像，或根据一个提示词生成 N 个变体（基于种子或提示词修饰）。
• 🧩 任意 Replicate 模型 — run_replicate_model 备用工具接受任意 owner/name[:version] 引用，并通过 get_model_schema 检查 OpenAPI 输入架构。可选使用 REPLICATE_MODEL_ALLOWLIST 设置允许列表。
• 📦 结构化输出 — 每个 generate_* 工具都会返回机器可读的 structuredContent 和人类可读内容，并遵循对应的工具 outputSchema（URL、提示词、格式、纵横比、各变体的种子等）。
• ⏳ 进度通知 — 批量生成和变体生成会向通过 progressToken 选择接收通知的客户端发送 notifications/progress，避免长时间运行过程不透明。
• 💬 精选提示词 — 提供 5 个现成的提示词模板（logo、portrait、svg-icon、product-shot、isometric-diagram），可在 Claude Desktop 的斜杠命令面板和 Cursor 的 @ 菜单中使用。
• 🏷️ 恰当的工具注释 — 正确设置 readOnlyHint / destructiveHint / openWorldHint / idempotentHint，方便客户端评估安全性和成本。
• 🪵 结构化日志记录 — 服务端错误通过 notifications/message 传递，而非 stderr。
• 🔌 通用 MCP 兼容性 — MCP 协议 2025-11-25；适用于 Claude Desktop、Cursor、Cline、Zed 以及任何符合规范的客户端。
• 🔍 生成历史记录 — 通过 imagelist、svglist 和 predictionlist 资源浏览过去的运行记录。

📚 文档

可用工具

generate_image

使用配置的图像模型（仅限允许列表中的模型）根据文本提示词生成图像。

{
  prompt: string;                // Required: Text description of the image to generate
  model_id?: string;             // Optional: Override image model (allowlist only)
  seed?: number;                 // Optional: Random seed for reproducible generation
  go_fast?: boolean;             // Optional: Run faster predictions with optimized model (default: true)
  megapixels?: "1" | "0.25";     // Optional: Image resolution (default: "1")
  num_outputs?: number;          // Optional: Number of images to generate (1-4) (default: 1)
  aspect_ratio?: string;         // Optional: Aspect ratio (e.g., "16:9", "4:3") (default: "1:1")
  output_format?: string;        // Optional: Output format ("webp", "jpg", "png") (default: "webp")
  output_quality?: number;       // Optional: Image quality (0-100) (default: 80)
  num_inference_steps?: number;  // Optional: Number of denoising steps (1-4) (default: 4)
  disable_safety_checker?: boolean; // Optional: Disable safety filter (default: false)
  support_image_mcp_response_type?: boolean; // Optional: Return embedded image content when supported (default: true)
}

generate_multiple_images

使用配置的图像模型（仅限允许列表中的模型）根据提示词数组生成多张图像。

{
  prompts: string[];             // Required: Array of text descriptions for images to generate (1-10 prompts)
  model_id?: string;             // Optional: Override image model (allowlist only)
  seed?: number;                 // Optional: Random seed for reproducible generation
  go_fast?: boolean;             // Optional: Run faster predictions with optimized model (default: true)
  megapixels?: "1" | "0.25";     // Optional: Image resolution (default: "1")
  aspect_ratio?: string;         // Optional: Aspect ratio (e.g., "16:9", "4:3") (default: "1:1")
  output_format?: string;        // Optional: Output format ("webp", "jpg", "png") (default: "webp")
  output_quality?: number;       // Optional: Image quality (0-100) (default: 80)
  num_inference_steps?: number;  // Optional: Number of denoising steps (1-4) (default: 4)
  disable_safety_checker?: boolean; // Optional: Disable safety filter (default: false)
  support_image_mcp_response_type?: boolean; // Optional: Return embedded image content when supported (default: true)
}

generate_image_variants

使用配置的图像模型（仅限允许列表中的模型）根据单个提示词生成同一图像的多个变体。

{
  prompt: string;                // Required: Text description for the image to generate variants of
  model_id?: string;             // Optional: Override image model (allowlist only)
  num_variants: number;          // Required: Number of image variants to generate (2-10, default: 4)
  prompt_variations?: string[];  // Optional: List of prompt modifiers to apply to variants (e.g., ["in watercolor style", "in oil painting style"])
  variation_mode?: "append" | "replace"; // Optional: How to apply variations - 'append' adds to base prompt, 'replace' uses variations directly (default: "append")
  seed?: number;                 // Optional: Base random seed. Each variant will use seed+variant_index
  go_fast?: boolean;             // Optional: Run faster predictions with optimized model (default: true)
  megapixels?: "1" | "0.25";     // Optional: Image resolution (default: "1")
  aspect_ratio?: string;         // Optional: Aspect ratio (e.g., "16:9", "4:3") (default: "1:1")
  output_format?: string;        // Optional: Output format ("webp", "jpg", "png") (default: "webp")
  output_quality?: number;       // Optional: Image quality (0-100) (default: 80)
  num_inference_steps?: number;  // Optional: Number of denoising steps (1-4) (default: 4)
  disable_safety_checker?: boolean; // Optional: Disable safety filter (default: false)
  support_image_mcp_response_type?: boolean; // Optional: Return embedded image content when supported (default: true)
}

generate_svg

使用配置的 SVG 模型（仅限允许列表中的模型）根据文本提示词生成 SVG/矢量输出。

{
  prompt: string;                // Required: Text description of the SVG to generate
  size?: string;                 // Optional: Size of the generated SVG (default: "1024x1024")
  style?: string;                // Optional: Style of the generated image (default: "any")
                                // Options: "any", "engraving", "line_art", "line_circuit", "linocut"
}

prediction_list

从 Replicate 获取近期预测记录列表。

{
  limit?: number;  // Optional: Maximum number of predictions to return (1-100) (default: 50)
}

get_prediction

获取特定预测的详细信息。

{
  predictionId: string;  // Required: ID of the prediction to retrieve
}

run_model

使用原始输入载荷运行允许列表中的 Replicate 模型（适用于视频或修复模型）。

{
  model_id: string;                // Required: Replicate model id (allowlist only)
  input?: Record<string, unknown>; // Optional: Raw input payload for the model
}

run_replicate_model

根据 owner/name[:version] 引用运行托管在 Replicate 上的任意模型。如果没有合适的精选工具，可将此工具用作备用方案。如果不清楚输入格式，请先调用 get_model_schema。

{
  model: string;                              // Required: 'owner/name' or 'owner/name:version'
  input: Record<string, unknown>;             // Required: Model input parameters
  prefer_wait?: number;                       // Optional: Seconds to block waiting for sync output (1-60, default 60)
  return_as?: "url" | "base64" | "both";      // Optional: How to return file outputs (default "url")
}

设置 REPLICATE_MODEL_ALLOWLIST 环境变量（以逗号分隔的 owner/name 条目），以限制可调用的模型。未设置 = 允许使用任意模型。已设置但为空 = 拒绝所有模型（服务会默认拒绝，而不会在未提示的情况下放行所有模型）。

get_model_schema

获取 Replicate 模型的 OpenAPI 输入架构和描述，以便为 run_replicate_model 传入正确的参数。

{
  model: string;  // Required: Replicate model reference in 'owner/name' form
}

可用资源

imagelist

浏览使用配置的图像模型生成的图像历史记录。

svglist

浏览使用配置的 SVG 模型生成的 SVG 输出历史记录。

predictionlist

浏览所有 Replicate 预测历史记录。

可用提示词

精选模板会显示在 Claude Desktop 的斜杠菜单和 Cursor 的 @ 调色板中。每个模板都会填入合理的默认值，然后委托给相应的生成工具。

提示词	描述	参数
logo	品牌/产品标志	brand、style?、palette?
portrait	写实肖像	subject、mood?、lens?
svg-icon	单一概念的矢量图标	concept、style?
product-shot	工作室产品摄影	product、surface?
isometric-diagram	等距技术插画	subject、emphasis?

结构化输出

每个 generate_* 工具都会返回人类可读的 content（文本 + 图像块）和与工具 outputSchema 匹配的机器可读 structuredContent。

工具	structuredContent 结构
generate_image	{ url, prompt, format, aspect_ratio, seed? }
generate_svg	{ url, prompt, size, style, svg? }
generate_multiple_images	{ images: [{ url, prompt }], format, aspect_ratio }
generate_image_variants	{ base_prompt, variation_mode, variants: [{ variant_index, url, prompt_used, seed? }], format, aspect_ratio }

支持 MCP 结构化输出的客户端可以直接使用 URL 和元数据，无需解析文本。

环境变量

变量	必填	用途
REPLICATE_API_TOKEN	是	Replicate 的 API 令牌。若缺少此项，服务会立即退出。
REPLICATE_IMAGE_MODEL_ID	否	覆盖 generate_image、generate_multiple_images、generate_image_variants 和 create_prediction 使用的默认精选图像模型。该值必须在内置图像允许列表中。
REPLICATE_SVG_MODEL_ID	否	覆盖 generate_svg 使用的默认 SVG 模型。该值必须在内置 SVG 允许列表中。
REPLICATE_MODEL_ALLOWLIST	否	以逗号分隔的 owner/name 条目，用于控制 run_replicate_model。未设置 = 允许使用任何模型。已设置但为空 = 全部拒绝（失败时默认拒绝）。该变量在进程启动时评估一次，因此请在 MCP 客户端的 env 块中设置（不要通过稍后加载的 dotenv 文件设置）。

💻 开发

1. 克隆仓库：

git clone https://github.com/awkoy/replicate-flux-mcp.git
cd replicate-flux-mcp

2. 安装依赖：

npm install

3. 启动 TypeScript 监视器：

npm run watch

4. 构建项目：

npm run build

5. 使用 MCP Inspector 对服务进行冒烟测试：

npm run inspector

6. 连接到客户端：

{
  "mcpServers": {
    "image-generation-mcp": {
      "command": "npx",
      "args": [
        "/Users/{USERNAME}/{PATH_TO}/replicate-flux-mcp/build/index.js"
      ],
      "env": {
        "REPLICATE_API_TOKEN": "YOUR REPLICATE API TOKEN"
      }
    }
  }
}

测试

此项目目前没有自动化测试套件。验证通过以下方式进行：

• npm run build — TypeScript 类型检查可以捕获大多数回归问题。
• npm run inspector — 通过官方 MCP Inspector 运行已构建的二进制文件，对工具、资源和提示词进行端到端冒烟测试。

欢迎贡献完善的测试框架（例如 Vitest + MCP stdio 客户端测试框架）。

⚙️ 技术详情

技术栈

• Model Context Protocol SDK - 用于工具和资源管理的核心 MCP 功能
• Replicate API - 提供对先进 AI 图像生成模型的访问
• TypeScript - 确保类型安全，并利用现代 JavaScript 功能
• Zod - 实现运行时类型验证，确保 API 交互可靠

配置

可以通过修改 src/config/index.ts 中的 CONFIG 对象，或设置 REPLICATE_IMAGE_MODEL_ID / REPLICATE_SVG_MODEL_ID 环境变量来覆盖默认值，从而配置服务：

export const CONFIG = {
  serverName: "replicate-flux-mcp",
  serverVersion: "0.4.1",
  imageModelId: process.env.REPLICATE_IMAGE_MODEL_ID ?? "black-forest-labs/flux-schnell",
  svgModelId: process.env.REPLICATE_SVG_MODEL_ID ?? "recraft-ai/recraft-v3-svg",
  pollingAttempts: 25,
  pollingInterval: 2000, // ms
  modelAllowlistConfigured: process.env.REPLICATE_MODEL_ALLOWLIST !== undefined,
  modelAllowlist: (process.env.REPLICATE_MODEL_ALLOWLIST ?? "")
    .split(",")
    .map((s) => s.trim())
    .filter(Boolean),
};

切换模型（无需修改代码）

启动服务时使用环境变量（适用于 npx、Cursor、Claude Desktop 等）。精选图像 / SVG 工具的覆盖模型必须在内置允许列表中：

# Stay on defaults:
REPLICATE_API_TOKEN=YOUR_TOKEN npx -y replicate-flux-mcp

# Switch to other allowlisted models
REPLICATE_IMAGE_MODEL_ID="google/imagen-4" \
REPLICATE_SVG_MODEL_ID="recraft-ai/recraft-v3-svg" \
REPLICATE_API_TOKEN=YOUR_TOKEN \
npx -y replicate-flux-mcp

modelAllowlist 在进程启动时根据 REPLICATE_MODEL_ALLOWLIST 评估一次。更改后请重启服务。

🔍 故障排除

常见问题

身份验证错误

• 确保已在环境中正确设置 REPLICATE_API_TOKEN
• 直接使用 Replicate API 测试令牌，验证其是否有效

触发安全过滤器

• 模型内置的安全过滤器可能会拦截某些提示词
• 尝试修改提示词，避免可能有问题的内容

超时错误

• 对于较大的图像或繁忙的服务，可能需要在配置中增加 pollingAttempts 或 pollingInterval
• 默认设置应适用于大多数用例

🤝 贡献

欢迎贡献！请按照以下步骤参与贡献：

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到该分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

如需提出功能请求或报告 Bug，请创建 GitHub issue。如果你喜欢此项目，欢迎为仓库点个星！

📄 许可证

此项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

🔗 资源

• Model Context Protocol 文档
• Replicate API 文档
• 免费试用合集
• Flux Schnell 模型
• Recraft V3 SVG 模型
• MCP TypeScript SDK
• Smithery 文档
• Glama.ai MCP 服务
• 作者：Yaroslav Boiko

🎨 示例

多个提示词	提示词变体

以下是一些工具使用示例：

使用 generate_multiple_images 批量生成图像

一次使用不同的提示词创建多张不同的图像：

{
  "prompts": [
    "A red sports car on a mountain road", 
    "A blue sports car on a beach", 
    "A vintage sports car in a city street"
  ]
}

使用 generate_image_variants 创建图像变体

使用种子为同一概念生成不同的演绎：

{
  "prompt": "A futuristic city skyline at night",
  "num_variants": 4,
  "seed": 42
}

或者使用提示词修饰语探索不同的风格：

{
  "prompt": "A character portrait",
  "prompt_variations": [
    "in anime style", 
    "in watercolor style", 
    "in oil painting style", 
    "as a 3D render"
  ]
}

---

由 Yaroslav Boiko ❤️ 制作