ComfyUI MCP

English · スペイン語

ComfyUI MCP — Model Context Protocol（MCP）経由の AI エージェント向け画像生成

ネットワーク内のあらゆる AI エージェントに SDXL 画像生成を接続します。 ComfyUI の推論（SDXL / RTX 3060）を Claude Code、Cursor、Windsurf、Hermes Gateway、および Model Context Protocol 対応のあらゆるクライアントに公開するオープンソースの MCP サーバーです。FastMCP HTTP/SSE ＋ GPU Arbiter により、クライアント側の依存関係はゼロ、処理はすべてお使いのハードウェア上で行われます。

タグ： mcp-server · comfyui · sdxl · image-generation · ai-agents · fastmcp · claude-code · cursor · hermes-gateway · gpu-arbiter · local-first · self-hosted

_{エージェントがプリセットを指定して画像をリクエストすると、ダウンロード URL が返されます。GPU はサーバー上で処理を行うため、クライアントに PyTorch をインストールする必要はありません。}

---

💡 開発の背景

マルチエージェント環境で画像を生成するには、各クライアントマシンに重い PyTorch ライブラリや専用 GPU をインストールし、複雑な設定を行う必要があります。ComfyUI MCP は、独立した HTTP/SSE ミドルウェアアダプターとして動作し、この問題を解決します。

• 🚀 ローカルへのインストール不要：クライアントやゲートウェイは、PyTorch をインストールしたり SDXL モデルをローカルにダウンロードしたりせずに、ポート 8201 経由で HTTP/SSE を使って画像生成を利用できます。
• 🧠 インテリジェントな GPU Arbiter：12GB の GPU（RTX 3060）上で llama-server（LLM）と ComfyUI を自動的に切り替え、VRAM の競合を防ぎます。
• 🎯 プロフェッショナルなプリセット：producto（RealVisXL V4.0）や realista（Juggernaut XL）などのプリセットを使って、すぐに本番環境で使える画像を生成できます。

---

🏗️ アーキテクチャとコンポーネントの役割分担

⚠️ 重要：システムの境界を理解する

comfyui-mcp は、MCP のトランスポートおよびインターフェース層のみを提供します。ComfyUI の推論エンジンやモデルの重みファイルは含まれていません。 Linux/Pop!_OS ホスト上のバックエンドサーバーのデプロイガイドについては、docs/SERVER_SETUP.md と docs/ARCHITECTURE.md を参照してください。

 +-------------------------------------------------------+
 |                 Clientes MCP (LAN)                    |
 | (Claude Code CLI / Cursor / Windsurf / Hermes Gateway)|
 +-------------------------------------------------------+
                             |
                             | HTTP / SSE (Puerto 8201)
                             v
 +-------------------------------------------------------+
 |                  comfyui-mcp Server                   |
 |           (FastMCP + Workflow JSON Builder)           |
 +-------------------------------------------------------+
                             |
                             | Loopback HTTP (Puerto 8188)
                             v
 +-------------------------------------------------------+
 |                 ComfyUI Backend Host                  |
 |  (PyTorch + CUDA + SDXL Checkpoints + GPU Arbiter)    |
 +-------------------------------------------------------+

---

📦 クイックインストール

要件

• Python 3.11+
• uv ≥ 0.13.4（推奨）または pip ≥ 26.2.2：それ以前のバージョンでは、侵害された CA emSign（GHSA-6q48-6c7w-9gw2）が引き続き信頼されます。pyproject.toml では uv の最小バージョンを [tool.uv] required-version で指定しています。

クローンしてインストール

git clone https://github.com/GermaniU/comfyui-mcp.git
cd comfyui-mcp

# Crear entorno virtual e instalar
uv venv
source .venv/bin/activate
uv pip install -e .

---

⚙️ 設定（環境変数）

.env ファイルを作成するか、次の変数をエクスポートしてください。

変数	デフォルト値	説明
COMFYUI_URL	http://127.0.0.1:8188	ComfyUI エンジンがリッスンするループバック URL です。
COMFYUI_PUBLIC_URL	http://<YOUR_SERVER_IP>:8188	画像ダウンロード用の公開／LAN ベース URL です。
MCP_HOST	0.0.0.0	MCP サーバーのバインド先ホストです。
MCP_PORT	8201	MCP サーバーの HTTP/SSE ポートです。
MCP_AUTH_TOKEN	(空 = 認証なし)	設定すると、HTTP/SSE リクエストごとに Authorization: Bearer <token> ヘッダーが必要になります。
MCP_CORS_ORIGINS	*	許可する CORS オリジンをカンマ区切りで指定します。ブラウザーで動作するクライアントにのみ適用されます。

セキュリティ： MCP_AUTH_TOKEN を設定しない場合、LAN 内のあらゆるデバイス、または CORS が * の状態で LAN 内のブラウザーから開いた Web ページが、画像を生成して GPU を使用できます。完全に信頼できるネットワークでない限り、トークンを設定することをおすすめします。

---

🛠️ 公開されるツール（ツールリファレンス）

1. generate_image（txt2img）

SDXL を使用して、テキストプロンプトから画像を生成します。

• パラメーター：
  • prompt（string、必須）：画像の説明（英語のほうが適切に機能します）。
  • preset（string、任意）：producto、realista、rapido、または anime。デフォルト："producto"。
  • aspect（string、任意）：1:1、4:5、5:4、9:16、16:9、3:2、2:3（約1MP）。デフォルト："1:1"。
  • negative_prompt（string、任意）：除外する要素。デフォルト：汎用の品質向上用ネガティブプロンプト。
  • seed（integer、任意）：再現性を確保するためのシード。デフォルト：ランダム。
  • batch（integer、任意）：1回の呼び出しで生成する画像数（1～4）。デフォルト：1。
  • checkpoint、lora、lora_strength、steps、cfg（任意）：プリセットの値を上書きします。
  • filename_prefix（string、任意）：出力ファイルの接頭辞。デフォルト："mcp"。
  • detail_face（bool、任意）：FaceDetailer パス（Impact Pack が必要です）。デフォルト：false。
  • preview（bool、任意）：モデルが結果を確認できるよう、JPEG サムネイル（約512px）も返します。ビジョン対応クライアント専用です。デフォルト：false。

2. img2img（Image-to-Image）

denoise レベルを指定して、生成済み画像（ComfyUI の output/ 内）を変化させます。

• パラメーター：
  • image_filename（string、必須）：生成済みファイルの名前（例：mcp_00001_.png）。
  • prompt（string、任意）：変換の指示。空の場合は、純粋な視覚的バリエーションになります。
  • denoise（float、任意）：0.0 は同一、1.0 は完全な新規画像です。デフォルト：0.55。
  • preset（string、任意）：デフォルト："realista"。
  • negative_prompt、seed、checkpoint、lora、lora_strength、steps、cfg、filename_prefix、preview（任意）。

3. generate_video（Wan 2.2）

Wan 2.2 TI2V 5B を使用して、短い MP4 クリップ（24fps）を生成します。画像を指定しない場合は txt2video になり、image_filename を指定すると、その画像を最初のフレームとしてアニメーション化します。ビデオモデルが必要です（SERVER_SETUP を参照）。RTX 3060 では、クリップ1本あたり数分かかります。

• パラメーター：
  • prompt（string、必須）：シーンと動き（カメラや被写体の動き）を英語で指定します。
  • aspect（string、任意）：16:9（1280x704）、9:16（704x1280）、または 1:1（960x960）。デフォルト："16:9"。
  • seconds（integer、任意）：長さ、1～5。デフォルト：3。
  • image_filename（string、任意）：アニメーション化する生成済み画像（例：mcp_00001_.png）。動画とアスペクト比を合わせることをおすすめします。
  • draft（bool、任意）：約480p（832x480、480x832、640x640）の下書きです。ピクセル数が半分以下で、大幅に高速に生成できます。最終版の前にプロンプトを試す場合に使用します。デフォルト：false。
  • negative_prompt、seed、steps、cfg、filename_prefix（任意）。接頭辞のデフォルト："mcp-video"。
  • preview（bool、任意）：最初のフレームの JPEG サムネイルです。デフォルト：false。

4. list_models

ComfyUI インスタンスで利用可能なチェックポイント、LoRA、プリセットの一覧を返します。

5. comfy_health

バックエンドのヘルスステータスを取得します。ComfyUI のバージョン、GPU の VRAM 使用量、キュー内のタスクを確認できます。

6. comfy_view_url

生成済みファイルの filename と subfolder を指定して、LAN 経由で直接ダウンロードできる URL を構築します。

---

🎨 プリセット一覧

プリセット	関連付けられたチェックポイント	ステップ数	CFG	用途
producto	RealVisXL_V4.0.safetensors	30	5.5	商品や製品のフォトリアルな商業写真（デフォルト）。
realista	juggernautXL_ragnarokBy.safetensors	30	5.0	幅広いフォトリアリズム（シーン、人物、環境）。
rapido	juggernautXL_ragnarokBy.safetensors + LoRA SDXL-Lightning	6	1.5	約5秒でプレビューや下書きを作成します。
anime	animagine-xl-3.1.safetensors	28	7.0	アニメ風イラスト（チェックポイントはサーバーに含まれていません）。

---

🧭 ComfyUI の他の MCP サーバーについて

サーバーは3つの系統に分かれており、それぞれ異なる課題を解決します。このサーバーはほかの2つと競合するのではなく、補完するものです。

	ComfyUI MCP（このサーバー）	workflow graph サーバー	クラウド画像 API
指定する内容	プロンプト + プリセット（producto、realista、rapido、anime）	JSON のノードグラフ（自分で設計）	リモートサービスへのプロンプト
ComfyUI の知識	不要	必要	不要
実行場所	自分の GPU（RTX 3060）	自分の GPU	サードパーティのサーバー
画像あたりのコスト	0（電気代のみ）	0	プロバイダーに応じた画像ごとの料金
プライバシー	プロンプトはネットワーク外に出ません	同様	プロンプトはクラウドに送信されます
LLM と GPU を共有	はい（GPU Arbiter、12 GB）	場合によります	N/A
クライアント	LAN 上の HTTP/SSE + stdio — クライアントに PyTorch は不要	通常はローカルの stdio	HTTP

ひとことで言うと：

• ノードグラフを完全に制御したい場合 → workflow graph サーバー（例：comfy-pilot）。
• GPU がなく、画像ごとに料金を支払ってもよい場合 → クラウド API（Flux、Nano Banana、GPT-image）。
• GPU を持っていて、LLM と GPU を共有しながら、ComfyUI を学ばずに画像を生成したい場合 → このサーバー。

---

🔗 MCP クライアントとの連携

Claude Code CLI の設定（~/.claude.json）

{
  "mcpServers": {
    "comfyui": {
      "url": "http://<YOUR_SERVER_IP>:8201/mcp"
    }
  }
}

Hermes Gateway の設定（~/.hermes/config.yaml）

mcp_servers:
  comfyui:
    url: "http://<YOUR_SERVER_IP>:8201/mcp"
    transport: "http"

Cursor / Windsurf / Claude Desktop の設定

URL http://<LAN_IP>:8201/mcp を指定して、SSE / HTTP タイプの MCP サーバーを追加します。

---

📋 不足しているコンポーネントとロードマップ（サーバー側の不足事項）

このリポジトリはMCP レイヤーを担うため、以下の要素はリポジトリの範囲外であり、ホストサーバー上で設定する必要があります。

1. ComfyUI バックエンドサーバー：Python と PyTorch CUDA を別途インストールする必要があります。
2. チェックポイントのダウンロード：SDXL モデルを手動でダウンロードし、ComfyUI サーバーの models/checkpoints/ ディレクトリに配置する必要があります。
3. GPU Arbiter スクリプト：gpu-broker.sh スクリプトと /etc/sudoers.d/gpu-arbiter ルールは、GPU を搭載した Linux マシン上に配置する必要があります。
4. 今後の MCP の改善点：
   • 動的なカスタム JSON ワークフローの挿入に対応します。
   • MCP ツール経由で処理キューのキャンセルとクリーンアップに対応します。
   • リアルタイムの進捗報告のため、WebSocket 接続に対応します。

---

🧪 ユニットテスト

uv run --with pytest --with pytest-asyncio pytest

---

📄 ライセンス

このプロジェクトは MIT ライセンスの下で公開されています。詳細については、LICENSE ファイルを参照してください。