STARWARCLOUD STARWAR.AI
返回市场
法尔_flux_上下文_最大_mcp_服务器

法尔_flux_上下文_最大_mcp_服务器

作者：PierrunoYT4 星标更新：2025-09-16
安装使用来源：spider==github.com

项目介绍

FAL FLUX.1 Kontext [Max] MCP 服务器

License: MIT TypeScript MCP FAL AI

这是一个提供对通过FAL AI平台访问FLUX.1 Kontext [Max]（前沿图像生成模型）的Model Context Protocol (MCP)服务器。该服务器支持高质量的图像生成，具有先进的文本渲染能力和卓越的上下文理解能力。

🔗 仓库: https://github.com/PierrunoYT/fal-flux-kontext-max-mcp-server

🚀 即刻可用！ 包含预构建可执行文件 - 无需编译。

✅ 增强可靠性: 服务器优雅地处理缺失的API密钥，不会崩溃，并且包括强大的错误处理机制。

功能

  • 前沿图像生成: 使用FLUX.1 Kontext [Max] - 通过FAL AI的最新前沿模型
  • 高级图像编辑: 具有上下文理解的强大图像编辑能力
  • 高级文本渲染: 超级文本集成和渲染能力
  • 上下文理解: 对复杂提示和上下文的理解增强
  • 自动图像下载: 生成的图像会自动保存到本地的images目录
  • 多种纵横比: 支持21:9, 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16, 和 9:21
  • 批量生成: 一次最多生成4张图像
  • 可重复结果: 可选种子参数以获得一致的输出
  • 双生成方法: 文本到图像和图像编辑的实时和异步队列生成
  • 灵活的输出格式: 支持JPEG和PNG格式
  • 安全控制: 可配置的安全容差级别（1-6）
  • 指导尺度控制: 微调模型遵循您的提示的程度（1.0-20.0）
  • 详细的响应: 返回本地文件路径和原始URL及元数据
  • 强大的错误处理: 缺失API密钥时优雅处理，不会导致服务器崩溃
  • 通用便携性: 无需本地安装即可在任何地方使用npx
  • 增强可靠性: 包括优雅的关闭处理器和全面的错误报告

预备条件

  • Node.js 18或更高版本
  • FAL AI API密钥

安装

1. 获取您的FAL AI API密钥

  • 访问FAL AI
  • 注册一个账户
  • 导航到您的仪表板
  • 生成一个API密钥

2. 克隆或下载

git clone https://github.com/PierrunoYT/fal-flux-kontext-max-mcp-server.git
cd fal-flux-kontext-max-mcp-server

3. 安装依赖项（可选）

服务器是预构建的，但如果您想要修改它：

npm install
npm run build

配置

🚀 推荐：通用npx配置（适用于任何地方）

最佳选择以实现便携性 - 在任何带有Node.js的机器上都能工作：

{
  "mcpServers": {
    "fal-flux-kontext-max": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/PierrunoYT/fal-flux-kontext-max-mcp-server.git"
      ],
      "env": {
        "FAL_KEY": "your-fal-api-key-here"
      }
    }
  }
}

优点：

  • ✅ 通用访问: 在任何带有Node.js的机器上都能工作
  • ✅ 无需本地安装: npx自动下载并运行
  • ✅ 始终最新版本: 从GitHub仓库拉取
  • ✅ 跨平台: 兼容Windows、macOS和Linux
  • ✅ 设置同步: 在您使用MCP客户端的所有地方都有效

替代方案：本地安装

如果您更喜欢本地安装，请使用路径助手：

npm run get-path

这将输出完整的MCP配置，带有正确的绝对路径。

对于Claude Desktop

添加到~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或%APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "fal-flux-kontext-max": {
      "command": "node",
      "args": ["path/to/fal-flux-kontext-max-mcp-server/build/index.js"],
      "env": {
        "FAL_KEY": "your-fal-api-key-here"
      }
    }
  }
}

对于Kilo Code MCP设置

添加到您的MCP设置文件中： C:\Users\[username]\AppData\Roaming\Kilo-Code\MCP\settings\mcp_settings.json

{
  "mcpServers": {
    "fal-flux-kontext-max": {
      "command": "node",
      "args": ["path/to/fal-flux-kontext-max-mcp-server/build/index.js"],
      "env": {
       - "FAL_KEY": "your-fal-api-key-here"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

可用工具

flux_kontext_max_generate

使用FLUX.1 Kontext [Max]实时处理生成图像。

参数：

  • prompt（必需）: 图像的文字描述
  • seed（可选）: 用于可重复生成的随机种子
  • guidance_scale（可选）: CFG比例 1.0-20.0（默认值：3.5）
  • sync_mode（可选）: 在返回之前等待生成（默认值：false）
  • num_images（可选）: 要生成的图像数量，1-4（默认值：1）
  • safety_tolerance（可选）: 安全级别 "1"-"6"（默认值："2"）
  • output_format（可选）: "jpeg" 或 "png"（默认值："jpeg"）
  • aspect_ratio（可选）: "21:9", "16:9", "4:3", "3:2", "1:1", "2:3", "3:4", "9:16", "9:21"（默认值："1:1"）

响应包括：

  • 用于即时访问的图像URL
  • 生成元数据（种子、请求ID、指导比例）
  • 文件信息（内容类型、尺寸）
  • 下载图像的本地文件路径

flux_kontext_max_generate_async

使用FLUX.1 Kontext [Max]异步队列处理生成图像，适用于较长的请求。

参数： 同 flux_kontext_max_generate

何时使用此工具：

  • 生成多张图像（2-4）
  • 复杂提示可能需要更长时间
  • 当常规工具超时时
  • 批量处理工作流

特性：

  • 基于队列的处理，带状态轮询
  • 5分钟超时，带进度更新
  • 生成进度的详细日志记录

flux_kontext_max_edit

使用FLUX.1 Kontext [Max]实时处理编辑图像。

参数：

  • prompt（必需）: 对图像进行编辑的文字描述
  • image_url（必需）: 要编辑的图像的URL（公共URL或base64数据URI）
  • seed（可选）: 用于可重复生成的随机种子
  • guidance_scale（可选）: CFG比例 1.0-20.0（默认值：3.5）
  • sync_mode（可选）: 在返回之前等待生成（默认值：false）
  • num_images（可选）: 要生成的图像数量，1-4（默认值：1）
  • safety_tolerance（可选）: 安全级别 "1"-"6"（默认值："2"）
  • output_format（可选）: "jpeg" 或 "png"（默认值："jpeg"）
  • aspect_ratio（可选）: "21:9", "16:9", "4:3", "3:2", "1:1", "2:3", "3:4", "9:16", "9:21"（默认值："1:1"）

响应包括：

  • 用于即时访问的编辑后图像URL
  • 生成元数据（种子、请求ID、指导比例）
  • 文件信息（内容类型、尺寸）
  • 下载图像的本地文件路径

flux_kontext_max_edit_async

使用FLUX.1 Kontext [Max]异步队列处理编辑图像，适用于较长的请求。

参数： 同 flux_kontext_max_edit

何时使用此工具：

  • 编辑复杂的图像可能需要更长时间
  • 生成多个编辑变体（2-4）
  • 当常规编辑工具超时时
  • 批量图像编辑工作流

特性：

  • 基于队列的处理，带状态轮询
  • 5分钟超时，带进度更新
  • 编辑进度的详细日志记录

📥 图像下载如何工作

FAL FLUX.1 Kontext [Max] MCP服务器会自动将生成的图像下载到您的本地机器。以下是完整的流程：

1. 图像生成流程

  1. API调用: 服务器调用FAL AI的FLUX.1 Kontext [Max] API
  2. 响应: FAL返回生成图像的临时URL
  3. 自动下载: 服务器立即下载图像到本地存储
  4. 响应: 返回本地路径和原始URL

2. 下载实现

下载函数 (downloadImage):

async function downloadImage(url: string, filename: string): Promise<string> {
  // 1. 解析URL并确定HTTP/HTTPS客户端
  const parsedUrl = new URL(url);
  const client = parsedUrl.protocol === 'https:' ? https : http;
  
  // 2. 如果不存在，则创建'images'目录
  const imagesDir = path.join(process.cwd(), 'images');
  if (!fs.existsSync(imagesDir)) {
    fs.mkdirSync(imagesDir, { recursive: true });
  }
  
  // 3. 创建文件写入流
  const filePath = path.join(imagesDir, filename);
  const file = fs.createWriteStream(filePath);
  
  // 4. 下载并管道到文件
  client.get(url, (response) => {
    response.pipe(file);
    // 处理完成和错误
  });
}

文件名生成 (generateImageFilename):

function generateImageFilename(prompt: string, index: number, seed: number): string {
  // 创建安全文件名: flux_kontext_max_prompt_seed_index_timestamp.jpeg
  const safePrompt = prompt
    .toLowerCase()
    .replace(/[^a-z0-9\s]/g, '')  // 移除特殊字符
    .replace(/\s+/g, '_')         // 将空格替换为下划线
    .substring( 0, 50);            // 限制长度
  
  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
  return `flux_kontext_max_${safePrompt}_${seed}_${index}_${timestamp}.jpeg`;
}

3. 文件存储详情

目录结构：

your-project/
├── images/                    # 自动创建的目录
│   ├── flux_kontext_max_mountain_landscape_123456_1_2025-06-24T18-30-45-123Z.jpeg
│   ├── flux_kontext_max_cute_robot_789012_1_2025-06-24T18-31-20-456Z.jpeg
│   └── ...

文件名格式：

  • 前缀: flux_kontext_max_
  • 提示: 前50个字符，经过清理（字母数字 + 下划线）
  • 种子: 用于生成的随机种子
  • 索引: 图像编号（对于多张图像）
  • 时间戳: ISO时间戳以确保唯一性
  • 扩展名: .jpeg 或 .png 根据输出格式

4. 响应格式

服务器返回本地和远程信息：

成功使用FLUX.1 Kontext [Max]生成了1张图像：

提示: "宁静的山景，白色书写着'FLUX'"
指导比例: 3.5
纵横比: 1:1
输出格式: jpeg
安全容差: 2
种子: 1234567890
请求ID: req_abc123

生成的图像:
图像1:
  本地路径: /path/to/project/images/flux_kontext_max_a_serene_mountain_landscape_1234567890_1_2025-06-24T18-30-45-123Z.jpeg
  原始URL: https://v3.fal.media/files/...
  尺寸: 1024x1024

图像已下载到本地的'images'目录。

示例用法

基础图像生成

生成一张金毛猎犬在向日葵田里玩耍的照片，上面写着“快乐的狗”大字

特定参数

生成一张图像，其中：
- 提示: "为一家科技初创公司设计的极简主义标志，干净的线条，带有'STARTUP'字样"
- 纵横比: 16:9
- 指导比例: 5.0
- 输出格式: png
- 图像数量: 2

高级用法与文本渲染

生成4张“未来城市的夜景，霓虹灯和飞行汽车，大型广告牌显示'未来城市2025'”
纵横比21:9，指导比例4.0，种子12345以获得可重复的结果

文本密集型提示（Kontext [Max]专长）

创建一张复古书店的照片，书脊上清晰可见的标题如《编码的艺术》、《数字梦想》和《未来故事》

图像编辑示例

基础图像编辑

编辑这张图片，在天空中添加彩虹
图片URL: https://example.com/landscape.jpg

复杂图像编辑

编辑图片：
- 提示: “在柜台旁边添加一个甜甜圈”
- 图片URL: https://v3.fal.media/files/rabbit/rmgBxhwGYb2d3pl3x9sKf_output.png
- 指导比例: 4.0
- 输出格式: png

添加文本到图像

在这张店面照片上添加“50%折扣”粗体红色文字
图片URL: https://example.com/storefront.jpg

风格转换和修改

将这张肖像转换为复古的棕色调效果，同时保持人物特征不变
图片URL: https://example.com/portrait.jpg

技术细节

架构

  • 语言: TypeScript，目标ES2022
  • 运行时: Node.js 18+，使用ES模块
  • 协议: Model Context Protocol (MCP) SDK v1.0.0
  • API客户端: FAL AI JavaScript客户端 v1.0.0
  • 验证: Zod模式验证

使用的API端点

  • 文本到图像实时: fal-ai/flux-pro/kontext/max/text-to-image（订阅方法）
  • 文本到图像异步: fal-ai/flux-pro/kontext/max/text-to-image（队列方法）
  • 图像编辑实时: fal-ai/flux-pro/kontext/max（订阅方法）
  • 图像编辑异步: fal-ai/flux-pro/kontext/max（队列方法）

错误处理

  • 优雅的API密钥处理: 即使未设置FAL_KEY，服务器也能继续运行
  • 无崩溃失败: 删除了导致连接中断的process.exit()调用
  • 空安全检查: 所有工具在执行前都会验证API客户端的可用性
  • 优雅关闭: 正确处理SIGINT和SIGTERM信号
  • API错误捕获: 详细的错误报告
  • 超时处理: 强大的异步请求管理，带进度更新
  • 用户友好消息: 清晰的错误描述而不是技术崩溃

开发

项目结构

├── src/
│   └── index.ts          # 主MCP服务器实现
├── build/                # 编译后的JavaScript（即用）
├── test-server.js        # 服务器测试工具
├── get-path.js          # 配置路径助手
├── example-mcp-config.json # 示例配置
├── package.json         # 项目元数据和依赖项
└── tsconfig.json        # TypeScript配置