ComfyUI_MCP Server（ComfyUI的ModelContextProtocol 服务端 | ModelContextProtocol Server for ComfyUI）

ComfyUI_MCP Server（ComfyUI向けModelContextProtocolサーバー | ModelContextProtocol Server for ComfyUI）

プロジェクト紹介 | プロジェクト紹介

ComfyUI_MCP Serverは、ComfyUI向けに設計された、疎結合で拡張性に優れた、設定駆動型のModel Context Protocol（MCP）サーバーです。ユーザーがカスタマイズしたワークフローに基づき、txt2imgやimg2imgなどのMCPサービス（ツール）を拡張できます。各MCPサービス（ツール）のパラメーターと動作は、JSON初期化とMCPツールデコレーターモジュールを通じて柔軟に拡張でき、AI画像生成や推論などのシナリオにおける自動化と統合に適しています。

ComfyUI_MCP Serverは、ComfyUI向けに設計された、疎結合で拡張性に優れた、設定駆動型のModel Context Protocol（MCP）サーバーです。ユーザーがカスタマイズしたワークフローに基づき、txt2imgやimg2imgなどのMCPサービス（ツール）を拡張できます。各MCPサービス（ツール）のパラメーターと動作は、JSON初期化とMCPツールデコレーターモジュールを通じて柔軟に拡張でき、AI画像生成や推論などのシナリオにおける自動化と統合に最適です。

動画デモ | 動画デモ

🎬 ComfyUI_MCP Serverの機能デモ（YouTube）

---

ディレクトリ構成 | ディレクトリ構成

mcp_server/
├── mcp_server/
│   ├── mcpserver.py         # 主入口，自动注册 tools 目录下所有工具 | Main entry, auto-registers all tools in the tools directory
│   ├── tools/               # 工具模块与mcp tool配置（每个mcp tool一个py和json）| Tool modules and configs (one .py and .json per mcp tool)
│   │   ├── txt2img.py
│   │   ├── txt2img_api.json
│   │   ├── img2img.py
│   │   ├── img2img_api.json
│   │   ├── {xxxx}.py        # 配合被调用的ComfyUI的工作流。可任意添加MCP工具配置，工具自动注册与API扩展机制。  
│   │   ├── {xxxx}_api.json  # Used in conjunction with the workflows of the callable ComfyUI, allowing for the addition of MCP tool configurations, with automatic registration and API extension mechanisms.
│   │   ├── ......
│   │   └── __init__.py
│   ├── utils.py             # 配置、模板、随机种子等通用工具 | Utilities for config, templates, random seed, etc.
│   ├── config.ini           # mcp服务与被调用的ComfyUI地址配置 | Service and ComfyUI address config
│   ├── logger.py & decorator.py                # 日志系统 | logs sys
│   └── __init__.py
├── workflows/               # MCP工具可实现的ComfyUI工作流json，与tools/对应。 | The "ComfyUI workflow json" that the "MCP tool" can achieve. Corresponding to "tools/".
│   ├── txt2img.json
│   ├── img2img.json
│   ├── {xxxx}.json          
│   ├── ......
├── pyproject.toml           # 构建配置与依赖 | Build config and dependencies
└── README.md                # 使用说明（本文件）| User guide (this file)

---

インストール・設定・実行 | インストール・設定・実行

python install.py # install(check item 2~3) & config(check item 1) 

run_mcp.bat #run on windows
./run_mcp.sh #run on linux

• デフォルトでは、ストリーミングHTTP（streamable-http）モードで実行されます
• tools/ ディレクトリ内のすべてのツールモジュールが自動的に登録されます

---

ComfyUI_MCPツールの自動登録とAPI拡張の仕組み | ツールの自動登録とAPI拡張

1. カスタムMCPツールとメソッドの実装 | カスタムMCPツールとメソッドの実装

txt2img を例にすると、新しいツールを追加するには、次の手順だけで済みます。

• tools/myapi.py を追加し、register_myapi_tool(mcp) を実装してMCPサービス（ツール）を登録します
• tools/myapi_api.json を追加して、パラメーターテンプレートを定義します（対象のComfyUIインスタンスのカスタムワークフローから、同名のAPIを _api サフィックス付きでエクスポートします）
• メインエントリを変更する必要はなく、自動的に有効になります

新しいツール（例：txt2img）を追加するには、次の手順を実行します。

• tools/myapi.py を追加し、register_myapi_tool(mcp) を実装してMCPサービス（ツール）を登録します
• tools/myapi_api.json を追加して、パラメーターテンプレートを定義します（対象のComfyUIインスタンスのカスタムワークフローから、同名のAPIを _api サフィックス付きでエクスポートします）
• メインエントリを変更する必要はなく、自動的に有効になります

代表的なメソッドの実装と戻り値の形式 | 代表的な使い方と戻り値の形式

テキストから画像生成（txt2img）| テキストから画像生成（txt2img）

# tools/txt2img.py 
def register_txt2img_tool(mcp):
    async def comfyui_txt2img_impl(prompt: str, pic_width: str, pic_height: str, negative_prompt: str, batch_size: str, model: str) -> str:
      ...
# 返回图片 Markdown 格式 | Returns image in Markdown format
      ...
        markdown_images = [f"![image]({url})" for url in image_urls]
        return "\n".join(markdown_images)

• ComfyUIのオンラインワークフローHTTP APIを呼び出して、結果を取得します。
• すべてのパラメーターは省略可能です。デフォルト値は、対応するJSONファイル tools/txt2img_api.json から取得されます。
• 画像のMarkdownリンクを返します。ドキュメントやフロントエンドでそのまま使用できます
• 上記の機能を実装して、対応するMCPサービス（ツール）としてラップします

---

2. MCPツールの自動登録 | MCPツールの自動登録

• mcpserver.py は tools/ ディレクトリ内のすべての .py ファイル（txt2img.py など）を自動的に走査し、それぞれの register_xxx_tool(mcp) 登録関数を呼び出します。

• 各ツールモジュールには register_xxx_tool(mcp) を実装し、@mcp.tool() デコレーターを通じてMCPサービス（ツール）を登録する必要があります。

• mcpserver.py automatically traverses all .py files in the tools/ directory (such as txt2img.py) and calls their register_xxx_tool(mcp) registration function.

• Each tool module must implement register_xxx_tool(mcp) and register the MCP service(tool) via the @mcp.tool() decorator.

例 | Example：

# tools/txt2img.py
def register_txt2img_tool(mcp):
    @mcp.tool()
    async def txt2img(prompt: str, pic_width: str = '512', ... ) -> str:
        ...

3. 設定駆動のパラメーター | 設定駆動のパラメーター

• 各 MCP サービス（ツール）のパラメーターシグネチャ、型、説明文は、同じ名前の JSON（例：tools/txt2img_api.json）から自動生成できます。呼び出し先の ComfyUI のカスタムワークフローから、同じ名前に _api を付けた API をエクスポートします。

• すべてのパラメーターは省略可能です。指定しない場合はテンプレートのデフォルト値が自動的に使用され、再帰的な seed のランダム化、モデルのホワイトリスト、batch_size の制限などのビジネスルールに対応しています。

• 新しい MCP サービス（ツール）の JSON テンプレートは、呼び出し先の ComfyUI のカスタムワークフローから、同じ名前に _api を付けた API をエクスポートして、tools ディレクトリに配置してください。

• 各 API のパラメーターシグネチャ、型、説明文は、同じ名前の JSON（例：tools/txt2img_api.json）から自動生成できます。

• MCP サービス（ツール）のパラメーターは省略可能です。指定しない場合はテンプレートのデフォルト値が使用されます。再帰的な seed のランダム化、モデルのホワイトリスト、batch_size の制限などのビジネスルールに対応しています。

• 新しい MCP サービス（ツール）では、呼び出し先の ComfyUI インスタンスのカスタムワークフローから、同じ API 名に _api サフィックスを付けてエクスポートした JSON テンプレートを、tools ディレクトリに配置してください。

サンプルスニペット tools/txt2img_api.json | サンプルスニペット：

{
  "5": {
    "inputs": {
      "width": 512,
      "height": 512,
      "batch_size": 1
    },
    "class_type": "EmptyLatentImage"
  }
}

4. リソースの登録と管理 | リソースの登録と管理

@mcp.resource("info//ckpt") デコレーターを使ってリソース型 API を登録でき、モデルなどのリソースを自動的に検出、管理できます。

@mcp.resource("info//ckpt") デコレーターを使ってリソース型 API を登録でき、モデルなどのリソースを自動的に検出、管理できます。

例 | 例：

@mcp.resource("info//ckpt")
async def list_checkpoints() -> list:
    # 返回所有可用的ckpt模型列表
    ...

---

MCP Inspector を使ったデバッグ | MCP Inspector を使ったデバッグ

MCP Inspector は、MCP サーバーのテストとデバッグに使用できる、公式推奨の対話型開発者ツールです。

MCP Inspector は、MCP サーバーのテストとデバッグに使用できる、公式推奨の対話型開発者ツールです。

• 公式ドキュメント | 公式ドキュメント：https://modelcontextprotocol.io/docs/tools/inspector

Inspector をすぐに起動する | Inspector をすぐに起動する

run_mcp.bat --inspector #run on windows
./run_mcp.sh --inspector #run on linux

• Inspector はローカルの MCP サーバーに接続でき、ツール、リソース、プロンプトなどを使った包括的な対話テストに対応しています。

• Inspector の Tools パネルでは、自動登録された API ツールをすべて確認し、パラメーターのテスト、戻り値の確認、例外のデバッグを行えます。

• Inspector はローカルの MCP サーバーに接続でき、ツール、リソース、プロンプトなどを使った包括的な対話テストに対応しています。

• Inspector の Tools パネルでは、自動登録された API ツールをすべて確認し、パラメーターのテスト、戻り値の確認、例外のデバッグを行えます。

詳しい使い方は公式 Inspector ガイドをご覧ください | 詳しくは公式 Inspector ガイドをご覧ください。

---

よくある質問 | よくある質問

• ComfyUI が起動していない、またはアドレスが間違っている：config.ini の設定を確認してください。

• 依存関係がインストールされていない：まず uv pip install -r pyproject.toml を実行してください。

• 新しいツールが反映されない：register_xxx_tool(mcp) が実装され、tools/ ディレクトリに配置されていることを確認してください。

• パラメーターの検証に失敗する：JSON テンプレートと実際のパラメーターの型、範囲を確認してください。（呼び出し先の ComfyUI のカスタムワークフローから、同じ名前に _api を付けた API をエクスポートし、tools/ ディレクトリに配置してください。）

• Inspector が接続できない：MCP サーバーが起動しており、ポートが使用中でないことを確認してください。

• ログが生成されない、または出力されない：config.ini の logging 設定を確認し、log_path のパスが存在し、書き込み権限があることを確認してください。

• MCP サービスの転送モードを切り替えられない：config.ini の transport パラメーターが正しく変更されていることを確認し、サービスを再起動してください。

• ComfyUI が起動していない、またはアドレスが間違っている：config.ini を確認してください。

• 依存関係がインストールされていない：uv pip install -r pyproject.toml を実行してください。

• 新しいツールが反映されない：register_xxx_tool(mcp) が実装され、tools/ ディレクトリに配置されていることを確認してください。

• パラメーターの検証に失敗する：JSON テンプレートと実際のパラメーターの型、範囲を確認してください。（呼び出し先の ComfyUI インスタンスのカスタムワークフローから、同じ名前の API に _api サフィックスを付けてエクスポートし、tools/ ディレクトリに配置してください。）

• Inspector が接続できない：MCP サーバーが起動しており、ポートが使用中でないことを確認してください。

• ログが生成されない、または出力されない：config.ini の logging 設定を確認し、log_path が存在し、書き込み権限があることを確認してください。

• MCP サービスの転送モードを切り替えられない：config.ini の transport パラメーターが正しく変更されていることを確認し、サービスを再起動してください。

---

貢献と拡張 | 貢献と拡張

API ツールやビジネスロジックの拡充に向けた PR や issue を歓迎します。 モデル、パラメーター、ビジネスルールをさらに統合する場合は、ツールモジュールと JSON 設定を追加または変更するだけでよく、メイン処理を変更する必要はありません。

API ツールやビジネスロジックの拡充に向けた PR や issue を歓迎します。 モデル、パラメーター、ビジネスルールをさらに統合する場合は、ツールモジュールと JSON 設定を追加または変更するだけでよく、メイン処理を変更する必要はありません。

---

最適化予定 | To Do

• パラメーター型の自動推論と検証の強化：よりスマートなパラメーター型推論と、より厳格な検証に対応し、堅牢性を高めます。

  パラメーター型推論と検証の強化：よりスマートな型推論と、より厳格な検証によって堅牢性を高めます。

• より充実したエラー処理とログ：詳細なエラーログ、例外の追跡、ユーザーにわかりやすいメッセージを追加します。

  エラー処理とログの強化：エラーログを詳細化し、例外を追跡するとともに、ユーザーにわかりやすいメッセージを追加します。

• ツール／設定のホットリロード：toolsディレクトリと設定ファイルのホットリロードに対応し、サービスを再起動せずに変更を反映できるようにします。

  ツール／設定のホットリロード：サービスを再起動せずに反映できるよう、toolsディレクトリと設定ファイルのホットリロードに対応します。

• 複数のComfyUIバックエンドへの対応：複数のComfyUIバックエンドインスタンスに同時に接続してスケジュールし、負荷分散や複数モデルによる推論を実現します。

  複数のComfyUIバックエンドへの対応：複数のComfyUIバックエンドインスタンスに接続してスケジュールし、負荷分散や複数モデルによる推論を実現します。

• マルチメディアデータのやり取りへの対応：画像、音声、動画などのマルチメディアデータの入出力と処理に対応します。

  マルチメディアデータのやり取りへの対応：画像、音声、動画などのマルチメディアデータの入力、出力、処理に対応します。

• ComfyUI HTTP APIとの連携をさらに充実させます。

  ComfyUI HTTP APIとの連携をさらに充実させます。

• ユニットテストとCIの改善：ユニットテストケースを追加し、継続的インテグレーション（CI）プロセスを導入して、コード品質を確保します。

  ユニットテストとCIの改善：ユニットテストを追加し、CIパイプラインを導入して、コード品質を確保します。