✨ SiliconFlow FLUX MCP 服务器 ✨

✨ 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
   

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
   

   编辑 .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 密钥，请使用逗号分隔。服务器将按顺序轮流使用。

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

   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. 生成された画像 URL を src 属性に指定した HTML <img> タグ。alt テキストは入力されたプロンプトに基づいて生成されます。
   • ⚠️ 重要：SiliconFlow が返す画像 URL には有効期限があります（通常は約 30 分）。保存しておきたい画像は、早めに保存してください。
2. 画像の生成時に実際に使用されたシード値（該当する場合）。
3. 画像の生成に使用された完全なプロンプトテキスト。

Docker デプロイガイド 🐳

1. Docker イメージをビルドする（プロジェクトのルートディレクトリで実行）：

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

2. Docker コンテナを実行する：

   方法 1：-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 イメージの名前とタグです。

   方法 2：--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 许可证授权。