使用说明

项目简介

本项目 'fal-ai-mcp' 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在为 LLM 应用提供通过文本生成图像的能力。它利用 FAL.ai 平台和 HiDream-ai/HiDream-I1-Full 模型，将强大的图像生成功能以标准化的 MCP 协议形式暴露出来。

主要功能点

文本到图像生成: 通过简单的文本提示，即可生成高质量的图像。
FAL.ai API 集成: 使用 FAL.ai 平台提供的 API 接口，稳定可靠。
详细的图像元数据: 返回包含图像 URL (或 Base64 编码数据)、尺寸、内容类型等完整信息的 JSON 响应。
易于集成: 完美兼容所有 MCP 协议的客户端应用。
一致且可靠的输出: 保证图像生成结果的稳定性和可预测性。

安装步骤

前提条件:

Python 3.13 或更高版本
已注册 FAL.ai 账号并获取 API Key
包管理器 'uv' 或 'pip'

安装方式:

方法一：直接从 GitHub 安装 (推荐)

打开终端，设置 'FAL_KEY' 环境变量为您的 FAL.ai API Key，然后运行以下命令 (推荐使用 'uv')：

export FAL_KEY="your-fal-api-key" && uvx git+https://github.com/OKitchen/fal-ai-mcp

或者使用 'pip':

export FAL_KEY="your-fal-api-key" && pip install git+https://github.com/OKitchen/fal-ai-mcp

方法二：本地克隆并安装

克隆仓库到本地：

git clone https://github.com/OKitchen/fal-ai-mcp.git
cd fal-ai-mcp

安装依赖：

uv pip install -e .
# 或
pip install -e .

服务器配置 (MCP 客户端配置)

为了让 MCP 客户端连接到 'fal-ai-mcp' 服务器，您需要在 MCP 客户端的配置文件 ('mcp_config.json' 或类似文件) 中添加服务器配置信息。

直接连接 GitHub 托管版本配置 (示例):

{
  "mcpServers": {
    "fal-ai-image-generator": {  // 服务器名称，客户端用此名称引用
      "command": "uvx",         // 启动服务器的命令，uvx 用于直接执行 GitHub 仓库
      "args": [                 // 命令参数
        "git+https://github.com/OKitchen/fal-ai-mcp" // GitHub 仓库 URL
      ],
      "env": {                   // 环境变量
        "FAL_KEY": "your-fal-api-key" // FAL.ai API Key，请替换为您的真实 Key
      }
    }
  }
}

本地环境使用配置 (示例):

如果您选择本地克隆并安装，可以使用以下配置 (请替换 '/path/fal-ai-mcp' 为您的本地项目路径)：

{
  "mcpServers": {
    "fal-ai-image-generator": {  // 服务器名称
      "command": "uv",         // 启动命令，uv 用于执行本地 Python 环境
      "args": [                 // 命令参数
        "--directory",        // 指定工作目录
        "/path/fal-ai-mcp",   // 本地项目路径，请替换为您的实际路径
        "run",                // 运行命令
        "-m",                 // 以模块方式运行
        "pypi_mcp"            // 模块名称，对应 src/pypi_mcp/__main__.py
      ],
      "env": {                   // 环境变量
        "FAL_KEY": "your-fal-api-key" // FAL.ai API Key，请替换为您的真实 Key
      }
    }
  }
}

注意:

请务必将 '"your-fal-api-key"' 替换为您在 FAL.ai 平台申请的 API Key。
本地环境配置中的 '/path/fal-ai-mcp' 需要替换为 'fal-ai-mcp' 仓库在您本地的实际路径。

基本使用方法

配置完成后，在 MCP 客户端中，您可以使用服务器名称 '"fal-ai-image-generator"' 来调用 'text_to_image_fal' 工具。

例如，发送如下 JSON-RPC 请求：

{
  "jsonrpc": "2.0",
  "method": "tool_call",
  "params": {
    "server": "fal-ai-image-generator",
    "tool_name": "text_to_image_fal",
    "arguments": {
      "prompt": "A beautiful sunset over the mountains"
    }
  },
  "id": "1"
}

服务器将返回包含生成图像数据 (通常为 Base64 编码的图像 URL) 的 JSON-RPC 响应。

关键词