ComfyUI MCP Server

ComfyUI MCP Server

自然な会話を通じて、AI 画像／音声／動画を生成し、ブラッシュアップできます

ローカルの ComfyUI インスタンスを使って、AI エージェントが画像、音声、動画を生成し、反復的にブラッシュアップできる軽量な MCP（Model Context Protocol）サーバーです。

サーバーを起動し、クライアントを接続して、ツールを呼び出します。それ以外はすべて任意です。

---

クイックスタート（2～3 分）

これで、すべてが正常に動作していることを確認できます。

1) クローンしてセットアップする

git clone https://github.com/joenorton/comfyui-mcp-server.git
cd comfyui-mcp-server
pip install -r requirements.txt

2) ComfyUI を起動する

ComfyUI がインストールされ、ローカルで実行されていることを確認します。

cd <ComfyUI_dir>
python main.py --port 8188

3) MCP サーバーを実行する

リポジトリのディレクトリから実行します。

python server.py

サーバーは次の場所で待ち受けます。

http://127.0.0.1:9000/mcp

4) 動作を確認する（AI クライアントは不要です）

付属のテストクライアントを実行します。

# Use default prompt
python test_client.py

# Or provide your own prompt
python test_client.py -p "a beautiful sunset over mountains"
python test_client.py --prompt "a cat on a mat"

test_client.py は次の処理を行います。

• MCP サーバーに接続します
• 利用可能なツールを一覧表示します
• サーバーのデフォルト設定（幅、高さ、ステップ数、モデルなど）を取得して表示します
• 指定したプロンプト（またはデフォルト）で generate_image を実行します
• その他すべてのパラメーターにサーバーのデフォルト設定を自動的に使用します
• 生成されたアセットの情報を出力します

この手順が成功すれば、システムは正常に動作しています。

注： テストクライアントは、設定ファイル、環境変数、または set_defaults 呼び出しで設定されたサーバーのデフォルト設定を使用します。必須なのは prompt パラメーターだけです。それ以外のすべてのパラメーターには、サーバーのデフォルト設定が自動的に使用されます。

以上です。

---

AI エージェントで使用する（Cursor／Claude／n8n）

サーバーが起動したら、AI クライアントに接続できます。

プロジェクト単位の .mcp.json ファイルを作成します。

{
  "mcpServers": {
    "comfyui-mcp-server": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:9000/mcp"
    }
  }
}

注： 一部のクライアントでは、"streamable-http" ではなく "type": "http" を使用します。どちらもこのサーバーで動作します。自動検出が機能しない場合は、type フィールドを変更してみてください。

AI クライアントを再起動すると、次のようなツールを呼び出せるようになります。

• generate_image
• view_image
• regenerate
• get_job
• list_assets

これが、主に想定されている使用方法です。

---

動作確認後にできること

サーバーの実行とクライアントの接続を確認すると、次の機能を利用できます。

• regenerate による反復的なブラッシュアップ（プロンプトを再入力する必要はありません）
• 信頼性の高い追加操作に使える、明示的なアセット識別
• 時間のかかる生成処理のジョブ監視とキャンセル
• AI のコンテキストへの画像の任意の追加（view_image）
• パラメーターを公開する、自動検出された ComfyUI ワークフロー
• よく使う設定の再入力を避けるための、設定可能なデフォルト値

以下の内容はすべて、ここでテストした基本的な一連の流れを基にしています。

移行に関する注意（以前のバージョン）

このプロジェクトの以前のバージョンを使ったことがある場合、いくつか変更点があります。

変わらない点

• 引き続きローカルの MCP サーバーを実行し、ComfyUI に処理を委ねます
• ワークフローは引き続き workflows/ ディレクトリに配置する JSON ファイルです
• 画像生成の基本的な動作に変更はありません

新機能

• Streamable HTTP トランスポートにより、以前の WebSocket ベースの方式を置き換え
• 明示的なジョブ管理（get_job、get_queue_status、cancel_job）
• 場当たり的な URL の代わりにアセット識別子を使用（ホスト名が変わっても安定）
• regenerate による反復処理のサポート（パラメーターを上書きして再実行）
• view_image による、エージェント向けの任意の視覚的フィードバック
• よく使うパラメーターの再入力を避けるための設定可能なデフォルト値

概念上の変更点

以前のバージョンは、シンプルなリクエスト／レスポンスの中継機能でした。 現在のバージョンは、反復処理と状態を保持する制御ループを中心に構成されています。

1 回の呼び出しで画像を生成することもできますが、次の操作も可能になりました。

• 特定の出力を参照する
• すべてを指定し直さずに結果をブラッシュアップする
• 時間のかかるジョブを監視してキャンセルする
• AI エージェントに生成画像を直接確認させる

以前の動作をお探しですか？

以前のバージョンのような、最小限の単発処理を行いたい場合は、次のようにしてください。

• test_client.py を実行する（元の使用パターンと同じです）
• generate_image をプロンプトだけ指定して呼び出す（残りはサーバーのデフォルト設定で処理されます）
• 追加のツールは無視する

新機能を使わない限り、移行は不要です。

利用可能なツール

生成ツール

• generate_image：画像を生成します（promptが必要です）
• generate_song：音声を生成します（tagsとlyricsが必要です）
• regenerate：既存のアセットを任意のパラメーターで上書きして再生成します（asset_idが必要です）

表示ツール

• view_image：生成された画像をインラインで表示します（画像のみ。音声や動画には対応していません）

ジョブ管理ツール

• get_queue_status：ComfyUI のキュー状態（実行中／保留中のジョブ）を確認します。非同期処理の状況を把握できます
• get_job：prompt_idを指定してジョブの完了状況を確認します。ジョブが完了したかどうかを確認します
• list_assets：最近生成されたアセットを参照します。AI のメモリと反復作業に役立ちます
• get_asset_metadata：アセットの完全な来歴とパラメーターを取得します。ワークフローの履歴も含まれます
• cancel_job：キューに登録済みまたは実行中のジョブをキャンセルします

設定ツール

• list_models：利用可能な ComfyUI モデルを一覧表示します
• get_defaults：現在のデフォルト値を取得します
• set_defaults：デフォルト値を設定します（任意で永続化できます）

ワークフローツール

• list_workflows：利用可能なワークフローをすべて一覧表示します
• run_workflow：任意のワークフローをカスタムパラメーターで実行します

公開ツール

• get_publish_info：公開状態（検出されたプロジェクトルート、公開ディレクトリ、ComfyUI 出力ルート、未設定の項目）を表示します
• set_comfyui_output_root：ComfyUI の出力ディレクトリを設定します（Comfy Desktop や標準以外のインストール環境で推奨。再起動後も設定は保持されます）
• publish_asset：生成されたアセットを、決定的な圧縮を適用してプロジェクトのウェブディレクトリに公開します（デフォルトは 600KB）

公開に関する注意事項：

• セッション単位：asset_idは現在のサーバーセッションでのみ有効です。再起動すると無効になります。
• 一般的なケースでは設定不要：公開ディレクトリは自動検出されます（public/gen、static/gen、またはassets/gen）。ComfyUI の出力ディレクトリを検出できない場合は、set_comfyui_output_rootで一度設定してください。
• 2 つのモード：デモ（ファイル名を明示）とライブラリ（ファイル名を自動生成し、マニフェストを更新）があります。ライブラリモードではmanifest_keyが必要です。
• マニフェスト：manifest_keyが指定されている場合のみ更新されます。
• 圧縮：サイズ制限を満たすよう段階的に圧縮します。満たせない場合は、明確なエラーを返します。

クイックスタート：

エージェントとの会話の流れの例：

ユーザー：「ウェブサイト用のヒーロー画像を生成して、hero.webp として公開してください」

エージェント： 公開設定を確認

• get_publish_info()を呼び出す → ステータスが「ready」であることを確認

エージェント： 画像を生成

• generate_image(prompt="a hero image for a website")を呼び出す → asset_idを取得

エージェント： アセットを公開

• publish_asset(asset_id="...", target_filename="hero.webp")を呼び出す → 成功

ユーザー：「今度はロゴを生成して、'site-logo' としてマニフェストに追加してください」

エージェント： マニフェストとともに生成して公開

• generate_image(prompt="a modern logo")を呼び出す → asset_idを取得
• publish_asset(asset_id="...", manifest_key="site-logo")を呼び出す → ファイル名を自動生成し、マニフェストを更新

詳しい使い方とテスト手順については、docs/HOW_TO_TEST_PUBLISH.mdを参照してください。

カスタムワークフロー

workflows/ディレクトリに JSON ファイルを配置して、カスタムワークフローを追加します。ワークフローは自動的に検出され、MCP ツールとして公開されます。

ワークフローのプレースホルダー

ワークフロー JSON でPARAM_*プレースホルダーを使用して、パラメーターを公開します。

• PARAM_PROMPT → prompt: str（必須）
• PARAM_INT_STEPS → steps: int（任意）
• PARAM_FLOAT_CFG → cfg: float（任意）

例：

{
  "3": {
    "inputs": {
      "text": "PARAM_PROMPT",
      "steps": "PARAM_INT_STEPS"
    }
  }
}

ツール名はファイル名から導出されます（例：my_workflow.json → my_workflowツール）。

---

設定

このサーバーでは、よく使うパラメーターの繰り返しを避けるため、デフォルト値を設定できます。デフォルト値は次の方法で設定できます。

• 実行時のデフォルト値：set_defaults ツールを使用します（再起動すると失われます）
• 設定ファイル：~/.config/comfy-mcp/config.json（永続的）
• 環境変数：COMFY_MCP_DEFAULT_* をプレフィックスとする変数

デフォルト値は、優先順位の高い順に、呼び出しごとの値 → 実行時のデフォルト値 → 設定ファイル → 環境変数 → ハードコードされたデフォルト値として解決されます。

設定の詳細については、docs/REFERENCE.md を参照してください。

---

詳細リファレンス

パラメーターの完全な一覧、戻り値のスキーマ、設定オプション、高度なワークフローのメタデータについては、次のドキュメントを参照してください。

• API リファレンス - ツール、パラメーター、戻り値、設定に関する完全なリファレンス
• アーキテクチャ - 設計上の決定事項とシステムの概要

プロジェクト構成

comfyui-mcp-server/
├── server.py              # Main entry point
├── comfyui_client.py      # ComfyUI API client
├── asset_processor.py     # Image processing utilities
├── test_client.py         # Test client
├── managers/              # Core managers
│   ├── workflow_manager.py
│   ├── defaults_manager.py
│   └── asset_registry.py
├── tools/                 # MCP tool implementations
│   ├── generation.py
│   ├── asset.py
│   ├── job.py             # Job management tools
│   ├── configuration.py
│   └── workflow.py
├── models/                # Data models
│   ├── workflow.py
│   └── asset.py
└── workflows/             # Workflow JSON files
    ├── generate_image.json
    └── generate_song.json

注意事項

• サーバーはデフォルトで localhost にバインドします。認証またはリバースプロキシを使用せずに、パブリックに公開しないでください。
• モデルが <ComfyUI_dir>/models/checkpoints/ に存在することを確認してください。
• サーバーは streamable-http トランスポートを使用します（WebSocket ではなく HTTP ベースです）。
• ワークフローは自動検出されます。コードの変更は不要です。
• アセットは24時間後に期限切れになります（設定可能）。
• view_image がサポートするのは画像（PNG、JPEG、WebP、GIF）のみです。
• アセットの識別には、堅牢性を高めるため、URL ではなく (filename, subfolder, type) を使用します。
• 来歴の追跡と再現性のため、ワークフローの履歴全体が保存されます。
• regenerate は保存済みのワークフローデータを使用し、パラメーターを上書きしてアセットを再作成します。
• セッション分離：list_assets はセッションでフィルタリングできるため、AI エージェントのコンテキストを整理できます。

トラブルシューティング

サーバーが起動しない場合：

• ComfyUI がポート8188（デフォルト）で実行されていることを確認してください。
• Python 3.8 以降がインストールされていることを確認してください（python --version）。
• すべての依存関係がインストールされていることを確認してください：pip install -r requirements.txt
• サーバーログで具体的なエラーメッセージを確認してください。

クライアントが接続できない場合：

• コンソールに「Server running at http://127.0.0.1:9000/mcp」と表示されていることを確認してください。
• サーバーに直接アクセスしてテストしてください：curl http://127.0.0.1:9000/mcp（MCP の応答が返るはずです）。
• .mcp.json がプロジェクトルート（またはクライアントに応じた正しい場所）にあることを確認してください。
• "type": "streamable-http" と "type": "http" の両方を試してください。どちらもサポートされています。
• Cursor 固有の問題については、docs/MCP_CONFIG_README.md を参照してください。

ツールが表示されない場合：

• workflows/ ディレクトリに PARAM_* プレースホルダーを含む JSON ファイルがあることを確認してください。
• ワークフローの解析エラーがないか、サーバーログを確認してください。
• ComfyUI に必要なカスタムノードがインストールされていることを確認してください（カスタムワークフローを使用している場合）。
• 新しいワークフローを追加した後、MCP サーバーを再起動してください。

アセットが見つからないエラーが発生する場合：

• アセットはデフォルトで24時間後に期限切れになります（COMFY_MCP_ASSET_TTL_HOURS で設定可能）。
• アセットはサーバーの再起動時に失われます（設計上、一時的なものです）。
• regenerate を使用する前に、get_asset_metadata でアセットの存在を確認してください。
• アセットが正常に登録されたか、サーバーログを確認してください。

既知の制限事項（v1.0）

• 一時的なアセットレジストリ：asset_id の参照が有効なのは、MCP サーバーの実行中（かつ TTL の期限内）のみです。再起動後は、以前に発行された asset_id を解決できず、それらのアセットに対する regenerate は失敗します。

コントリビューション

イシューやプルリクエストを歓迎します。開発ガイドラインについては、CONTRIBUTING.md を参照してください。

謝辞

• @venetanji - streamable-http の基盤と PARAM_* システム

メンテナー

@joenorton

ライセンス

Apache License 2.0