Flux MCP Server Python

✨ SiliconFlow FLUX MCP 服务器 ✨

English | 中文

🚀 项目概览

这个MCP服务器允许语言模型通过 SiliconFlow FLUX 系列模型生成图像。项目基于 Python、mcp-sdk 及 FastMCP 框架实现，专为 Streamable HTTP 传输协议 设计，旨在作为独立的 HTTP 服务运行，适用于 Docker 容器化部署或直接在物理/虚拟机上运行。

主要特性 🌟

• 🎨 图像生成工具: 向 MCP 客户端提供一个名为 generate_image 的核心工具。
• 🤖 多模型支持: 允许在图像生成时指定不同的 SiliconFlow FLUX 模型。
• ⚙️ 参数可配置: 支持自定义图像的宽高比、推理步数、引导强度及种子(seed)。
• 🔑 API密钥轮询: 可配置一个以逗号分隔的 SiliconFlow API 密钥列表。服务器将以轮询方式使用这些密钥，以增强服务可靠性并辅助管理速率限制。
• 🔧 智能参数处理: 采用增强的参数处理机制，自动兼容各种MCP客户端的参数格式，提高稳定性。
• 🛠️ 环境变量配置: 通过 .env 文件或系统环境变量进行便捷配置。
• 🐳 Docker 就绪: 包含 Dockerfile，简化容器化部署流程。
• 📜 日志记录与轮换: 实现日志文件轮换功能，便于服务监控与问题排查。

重要提示：关于语言模型兼容性 💡

本服务器采用了增强的参数处理机制，能够自动处理不同客户端发送的各种参数格式，包括JSON字符串、嵌套结构等。但为了确保最佳交互效果和稳定性，强烈建议您在配置 MCP 客户端时，选用能够精确遵循工具调用规范大型语言模型，包括：

• Google Gemini 2.5 系列
• OpenAI GPT-4.x (不包括nano) / O 系列
• DeepSeek R1 / V3 系列
• Claude Sonnet / Haiku 系列

为什么这很重要？

一些较旧或能力较弱的小型模型，在理解和执行 MCP 工具调用指令时，可能无法严格按照工具中定义的 arguments 格式（例如，错误地添加包裹层、遗漏必需参数或错误处理参数类型）。这种不匹配可能导致工具调用失败，甚至在某些情况下导致服务器端出现崩溃。

系统要求 ✅

• 🐍 Python: 版本需为 3.11 或更高。
• ⚡ uv: 一个用 Rust 编写的高性能 Python 包管理工具。

- 安装指南: curl -LsSf https://astral.sh/uv/install.sh | sh (Linux/macOS) 或 powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" (Windows PowerShell)。请根据您的操作系统选择合适的命令，并在安装后重启终端以确保 uv 命令可用。

• 🗝️ SiliconFlow API 密钥: 至少需要一个。请从 SiliconFlow官网 获取。
• 🐳 Docker (可选): 若计划在容器中运行本服务器，则需要安装 Docker。

本地安装与设置 🛠️

1. 克隆代码仓库:

    git clone https://github.com/snakeying/Flux-mcp-server-python.git
    cd flux-mcp-server-python

1. 创建并激活 Python 虚拟环境 (推荐):

使用 uv:

    uv venv
    source .venv/bin/activate  # Linux/macOS
    # .venv\Scripts\activate    # Windows (cmd)
    # .\.venv\Scripts\Activate.ps1 # Windows (PowerShell)

1. 配置 API 密钥:

复制项目根目录下的 .env.example 文件为 .env:

    cp .env.example .env

编辑 .env 文件，并填入您的 SiliconFlow API 密钥:

    SILICONFLOW_API_KEYS=sk-您的密钥1,sk-您的密钥2_若有多个

    # 可选: 覆盖默认的图像生成参数
    # DEFAULT_MODEL_ID=Pro/black-forest-labs/FLUX.1-schnell
    # DEFAULT_ASPECT_RATIO="16:9"
    # DEFAULT_NUM_INFERENCE_STEPS=25
    # DEFAULT_GUIDANCE_SCALE=7.0

    # 可选: 覆盖默认的服务器 HTTP 设置
    # MCP_HTTP_HOST=0.0.0.0
    # MCP_HTTP_PORT=8008 # 注意：若在此处配置，本地运行命令可不带 --port 参数，除非想覆盖
    # MCP_LOG_LEVEL=INFO # 日志级别: DEBUG, INFO, WARNING, ERROR, CRITICAL

- 若提供多个 API 密钥，请使用逗号分隔。服务器将按顺序轮流使用。

1. 安装依赖及服务器:

在已激活的虚拟环境中执行:

    uv pip install -e .

此命令将以可编辑模式安装服务器，使得 flux-mcp-server 命令在当前环境中可用。

本地运行服务器 🚀

完成安装和配置后，在激活的虚拟环境中执行：

flux-mcp-server --host 0.0.0.0 --port 8008

• 若仅允许本地连接，可将 0.0.0.0 替换为 localhost 或 127.0.0.1。
• 8008 为服务器监听的端口号，可按需修改 (如果 .env 文件中设置了 MCP_HTTP_PORT，命令行参数会覆盖它)。
• 服务器启动后，控制台将显示运行日志，如 Uvicorn running on http://0.0.0.0:8008。
• 日志文件将写入项目根目录下的 logs/flux_mcp_server.log，并支持基于大小的轮换 (默认每 5MB 一个文件，保留 1 个备份)。

配置 MCP 客户端 (例如 Cherry Studio 或者 任意支持CSS渲染的客户端) 🤝

本服务器采用 Streamable HTTP 传输协议。请按以下方式配置您的 MCP 客户端：

1. 启动 Python MCP 服务器: 参考上一节 (例如，执行 flux-mcp-server --port 8008)。
2. 在 MCP 客户端的服务器配置部分：

* 类型 (Type): 选择 可流式传输的HTTP (streamableHttp)。 * URL: 输入正在运行的服务器的访问地址。 * 若服务器与客户端在同一台机器: http://localhost:8008/mcp (请将 8008 替换为服务器实际监听的端口。/mcp 是客户端通常请求的路径，服务器会通过重定向（至 /mcp/）或直接处理来响应）。 * 若服务器部署在不同机器，请使用服务器的 IP 地址或主机名。 * 命令 (Command)、参数 (Arguments)、环境变量 (Environment Variables - 特指客户端对此服务器的配置): 这些字段应保持为空或不适用。服务器是独立运行的，其 API 密钥通过自身环境（如 .env 文件或 Docker 启动时传递的环境变量）获取。

generate_image 工具使用指南 🛠️

服务器运行且客户端配置完成后，即可使用 generate_image 工具，配合system prompt 效果更佳！

工具参数详解:

• prompt (字符串, 必需): 用于图像生成的详细文本提示 (推荐使用英文)。
• model_id (字符串, 可选): 指定使用的 SiliconFlow 模型。

- 默认值: black-forest-labs/FLUX.1-schnell (或由 .env 文件中的 DEFAULT_MODEL_ID 决定)。 - 支持模型列表: black-forest-labs/FLUX.1-schnell, black-forest-labs/FLUX.1-dev, Pro/black-forest-labs/FLUX.1-schnell, LoRA/black-forest-labs/FLUX.1-dev。

• aspect_ratio (字符串, 可选): 期望的图像宽高比。

- 默认值: 1:1 (或由 .env 文件中的 DEFAULT_ASPECT_RATIO 决定)。 - 支持的宽高比字符串: "1:1", "1:2", "3:2", "3:4", "16:9", "9:16"。服务器将自动映射为 API 支持的像素尺寸。

• num_inference_steps (整数, 可选): 推理步数 (有效范围 1-50)。

- 默认值: 20 (或由 .env 文件中的 DEFAULT_NUM_INFERENCE_STEPS 决定)。

• guidance_scale (浮点数, 可选): 提示词引导强度。

- 默认值: 7.5 (或由 .env 文件中的 DEFAULT_GUIDANCE_SCALE 决定)。

• seed (整数, 可选, >=0): 用于结果可复现的随机数种子。

工具输出格式:

该工具返回一个多行字符串，包含以下内容：

1. 一个 HTML ` 标签，其 src 属性指向生成的图像 URL，alt` 文本根据输入的提示生成。

* ⚠️ 重要提示: SiliconFlow 返回的图像 URL 具有时效性 (通常约为 30 分钟)。请及时保存您希望保留的图片。

1. 生成该图像时实际使用的种子值 (如果适用)。
2. 生成该图像时使用的完整提示文本。

Docker 部署指南 🐳

1. 构建 Docker 镜像 (在项目根目录下执行):

    docker build -t flux-mcp-server-py:latest .

1. 运行 Docker 容器:

方式一：通过 -e 单独设置环境变量 (适用于少量关键变量)

    docker run -d --rm \
      -p 8008:8080 \
      -e SILICONFLOW_API_KEYS="sk-您的密钥1,sk-您的密钥2" \
      -e MCP_LOG_LEVEL="INFO" \
      -v /您宿主机的日志目录路径:/app/logs \
      --name my_flux_mcp_service \
      flux-mcp-server-py:latest

    # 可选的额外环境变量:
    # -e MCP_HTTP_HOST="0.0.0.0"  # 覆盖默认主机设置
    # -e MCP_HTTP_PORT="8080"     # 覆盖默认端口设置
    # -e DEFAULT_MODEL_ID="Pro/black-forest-labs/FLUX.1-schnell"  # 覆盖默认模型

参数说明: - -d: 使容器在后台运行。 - --rm: 容器停止时自动将其移除。 - -p 8008:8080: 将宿主机的 8008 端口映射到容器内部的 8080 端口 (容器内服务监听 8080)。客户端应配置连接到宿主机的 8008 端口 (例如 http://localhost:8008/mcp)。 - -e SILICONFLOW_API_KEYS="sk-您的密钥1,sk-您的密钥2": 关键，通过环境变量向容器传递 API 密钥。 - -e MCP_LOG_LEVEL="INFO": (可选) 设置应用的日志级别。 - 其他 -e 参数可用于覆盖代码或 .env 文件中的默认设置，例如 DEFAULT_MODEL_ID 等。 - -v /您宿主机的日志目录路径:/app/logs: 推荐。将宿主机的一个目录 (例如 /data/flux_mcp_logs，请替换为实际有效路径) 挂载到容器内的 /app/logs 目录。此操作可将容器产生的日志文件持久化存储到宿主机。请确保宿主机上的该目录已创建。 - --name my_flux_mcp_service: 为容器指定一个易于管理的名称。 - flux-mcp-server-py:latest: 您构建的 Docker 镜像名称及标签。

方式二：通过 --env-file 传递所有配置 (推荐用于管理多个配置项)

如果您在本地有一个 .env 文件 (可以从 .env.example 复制并修改)，并且希望容器使用该文件中的所有配置，可以使用 --env-file 标志：

    docker run -d --rm \
      -p 8008:8080 \
      --env-file ./.env \
      -v /您宿主机的日志目录路径:/app/logs \
      --name my_flux_mcp_service \
      flux-mcp-server-py:latest

    # 注意: .env 文件应位于执行 docker run 命令的当前目录下

- 使用此方式时，Docker 会读取指定的 .env 文件，并将其中的每一行 KEY=VALUE 设置为容器的环境变量。 - 这对于管理较多配置项（如 API 密钥、默认模型、日志级别等）更为便捷，无需在命令行中通过多个 -e 手动指定。 - 注意：通过 --env-file 设置的变量会覆盖 Dockerfile 中 ENV 指令设置的同名变量，但可能会被后续的 -e 标志覆盖（如果同时使用）。

故障排除与支持 🧐

• 请检查服务器的控制台输出以及项目根目录下 logs/flux_mcp_server.log 文件中的日志信息。
• 确认 .env 文件中的 SILICONFLOW_API_KEYS 已正确配置且密钥有效。
• 确保 Python 环境版本为 3.11 或更高。
• 检查 uvicorn 及项目其他依赖是否已在当前 Python 环境中正确安装。
• 若从其他设备连接服务器，请确保服务器启动时使用了 --host 0.0.0.0，并且网络防火墙允许访问指定端口。
• 若遇到与 MCP 协议本身相关的问题或疑问，可以查阅 Model Context Protocol 官方文档。

许可证信息 ⚖️

本项目基于 MIT 许可证授权。