✨ SiliconFlow FLUX MCP 服务器 ✨

<h1 align="center">
✨ SiliconFlow FLUX MCP 服务器 ✨
</h1>

<p align="center">
<br> <a href="README-EN.md">English</a> | <strong>中文</strong>
</p>

🚀 项目概览

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

<p align="center">






</p>

主要特性 🌟

- 🎨 图像生成工具: 向 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

    

2. 创建并激活 Python 虚拟环境 (推荐):
使用 uv:

    uv venv

    source .venv/bin/activate  # Linux/macOS

    # .venv\Scripts\activate    # Windows (cmd)

    # .\.venv\Scripts\Activate.ps1 # Windows (PowerShell)

    

3. 配置 API 密钥:
复制项目根目录下的 .env.example 文件为 .env:

    cp .env.example .env

    

    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

    

4. 安装依赖及服务器:
在已激活的虚拟环境中执行:

    uv pip install -e .

    

本地运行服务器 🚀

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

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 启动时传递的环境变量）获取。

该工具返回一个多行字符串，包含以下内容：
1. 一个 HTML ` 标签，其 src 属性指向生成的图像 URL，alt 文本根据输入的提示生成。
⚠️ 重要提示: SiliconFlow 返回的图像 URL 具有时效性 (通常约为 30 分钟)。请及时保存您希望保留的图片。
2. 生成该图像时实际使用的种子值 (如果适用)。
3. 生成该图像时使用的完整提示文本。

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

    

方式一：通过 -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"  # 覆盖默认模型

    

方式二：通过 --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 命令的当前目录下

    

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

许可证信息 ⚖️

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