Skip to main content
Glama
zjf2671

hh-mcp-comfyui

by zjf2671
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

ComfyUI MCP 服务

English 简体中文 Python 3.12+ License

这是一个基于Model Context Protocol (MCP)的ComfyUI图像生成服务，通过API调用本地ComfyUI实例生成图片。

功能特性

  • 通过MCP协议提供图像生成服务，实现自然语言生图自由

  • 支持动态替换工作流中的提示词和尺寸等参数

  • 自动加载workflows目录下的工作流文件作为资源

Related MCP server: comfyui-mcp-server

新增功能记录

  • [2025-06-29] 支持kontext图片编辑工作流 edit-image-85457440acc11a9f386f8ef284fd62f2.jpg

  • [2025-05-11] 支持工作流文件目录动态配置

  • [2025-05-09] 增加docker构建方式,支持Python 3.12+

  • [2025-05-07] 增加pip构建方式

  • [2025-05-06] 把项目目录src/hh修改成src/hh_mcp_comfyui,增加uvx构建方式

  • [2025-04-26] 增加图生图和移除背景样例工作流及支持图生图工具

  • [2025-04-20] 加入文生图生成工具

效果

  • Cherry Studio中使用效果 image-b8f946109d63fe1ccb5e2d63933e3f9e.png

  • Cline中使用效果 cline_gen_image-48d8515e0b59cd313879c62a1546162d.png ComfyUI_00020_-d9171f87fc9e67fcc1966cdbfb952a0c.png

安装依赖

1. 确保已安装Python 3.12+

2. 使用uv管理Python环境：

  • 安装uv:

    # On macOS and Linux.
$ curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows.
$ powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 更新uv(非必要操作):
$ uv self update

测试运行服务

  • uvx方式

    $ uvx hh-mcp-comfyui

INFO:hh_mcp_comfyui.server:Scanning for workflows in: C:\Users\tianw\AppData\Local\uv\cache\archive-v0\dp4MTo0f1qL0DdYF_BYCL\Lib\site-packages\hh_mcp_comfyui\workflows
INFO:hh_mcp_comfyui.server:Starting ComfyUI MCP Server...

  • pip方式

    $ pip install hh_mcp_comfyui

$ python -m hh_mcp_comfyui

INFO:hh_mcp_comfyui.server:Scanning for workflows in: F:\Python\Python313\Lib\site-packages\hh_mcp_comfyui\workflows
INFO:hh_mcp_comfyui.server:Starting ComfyUI MCP Server...

出现上面的信息表示服务启动成功

使用方法

必须确保本地ComfyUI实例正在运行(默认地址: http://127.0.0.1:8188) ComfyUI安装地址

Cherry Studio、Cline、Cursor等客户端的使用方式

{
  "mcpServers": {
    "hh-mcp-comfyui": {
      "command": "uvx",
      "args": [
        "hh-mcp-comfyui@latest"
      ],
      "env": {
        "COMFYUI_API_BASE": "http://127.0.0.1:8188",
        "COMFYUI_WORKFLOWS_DIR": "/path/hh-mcp-comfyui/workflows"
      }
    }
  }
}

需要先执行命令窗口先执行：pip install hh_mcp_comfyui

{
  "mcpServers": {
    "hh-mcp-comfyui": {
      "command": "python",
      "args": [
        "-m",
        "hh_mcp_comfyui"
      ],
      "env": {
        "COMFYUI_API_BASE": "http://127.0.0.1:8188",
        "COMFYUI_WORKFLOWS_DIR": "/path/hh-mcp-comfyui/workflows"
      }
    }
  }
}

前提是已安装docker

{
  "mcpServers": {
    "hh-mcp-comfyui": {
      "command": "docker",
      "args": [
          "run",
          "--net=host",
          "-v",
          "/path/hh-mcp-comfyui/workflows:/app/workflows",
          "-i",
          "--rm",
          "zjf2671/hh-mcp-comfyui:latest"
      ],
      "env": {
        "COMFYUI_API_BASE": "http://127.0.0.1:8188"
      }
    }
  }
}

样例工作流copy到指定工作流目录：

（注意：使用下面uvx或pip方式找到你的安装工作流目录的位置把样例工作流添加进去，然后重启你的MCP服务）

  • uvx

    $ uvx hh-mcp-comfyui

    image-2-f89caf964efbccdad7b6fa2672d1cac0.png

  • pip

    #首先安装依赖
$ pip install hh_mcp_comfyui
$ python -m hh_mcp_comfyui

    image-3-03a069f40492fea9947a351b8707aa3f.png

测试

使用MCP Inspector测试服务端工具

  • uvx方式

    $ npx @modelcontextprotocol/inspector uvx hh-mcp-comfyui

  • pip方式

    $ pip install hh_mcp_comfyui
$ npx @modelcontextprotocol/inspector python -m hh_mcp_comfyui

  • docker方式

    $ npx @modelcontextprotocol/inspector docker run --net=host -i --rm zjf2671/hh-mcp-comfyui

然后点击连接如图即可调试： image-1-44c6a003ee317093afe5a61cfe028720.png

使用注意事项（针对没有用过comfyui的特别注意）

  • 默认工作流为t2image_bizyair_flux

  • 图片尺寸默认为1024x1024

  • 服务启动时会自动加载workflows目录下的所有JSON工作流文件

  • 如果你使用的是本项目中的样例工作流需要在comfyui中下载个插件，详细操作请查看：样例工作流插件安装教程

  • 如果使用你本地的comfyui工作流的话，先要保证你的工作流能在comfyui正常运行，然后需要导出(API)的JSON格式，并放入到你本地的/path/hh_mcp_comfyui/workflows目录中

添加新工作流

  1. 将工作流JSON文件放入/path/hh_mcp_comfyui/workflows目录中

    如果是uvx和pip启动方式请看上面 《样例工作流copy到指定工作流目录》 的使用方式

  2. 重启服务自动加载新工作流

开发

项目结构

.
├── .gitignore
├── .python-version
├── pyproject.toml
├── README.md
├── uv.lock
├── example/              # 示例工作流目录
│   └── workflows/
│       ├── i2image_bizyair_sdxl.json
│       ├── t2image_bizyair_flux.json
│       ├── i2image_cogview4.json
│       └── t2image_sd1.5.json
├── src/                  # 源代码目录
│   └── hh_mcp_comfyui/
│       ├── comfyui_client.py    # ComfyUI客户端实现
│       ├── server.py            # MCP服务主文件
│       └── workflows/           # 工作流文件目录

初始化项目开发环境：

# Clone the repository.
$ git clone https://github.com/zjf2671/hh-mcp-comfyui.git

$ cd hh-mcp-comfyui

# Initialized venv
$ uv venv

# Activate the virtual environment.
$ .venv\Scripts\activate

# Install dependencies.
$ uv lock
Resolved 30 packages in 1ms

# sync dependencies.
$ uv sync
Resolved 30 packages in 2.54s
Audited 29 package in 0.02ms

检查服务是否正常

$ uv --directory 你本地安装目录/hh-mcp-comfyui run hh-mcp-comfyui

INFO:__main__:Scanning for workflows in: D:\cygitproject\hh-mcp-comfyui\src\hh_mcp_comfyui\workflows
INFO:__main__:Registered resource: workflow://t2image_bizyair_flux -> t2image_bizyair_flux.json
INFO:__main__:Starting ComfyUI MCP Server...

使用MCP Inspector测试服务端工具

$ npx @modelcontextprotocol/inspector uv --directory 你本地安装目录/hh-mcp-comfyui run hh-mcp-comfyui

MCP配置

{
  "mcpServers": {
    "hh-mcp-comfyui": {
      "command": "uv",
      "args": [
        "--directory",
        "项目绝对路径（例如：D:/hh-mcp-comfyui）",
        "run",
        "hh-mcp-comfyui"
      ],
      "env": {
        "COMFYUI_API_BASE": "http://127.0.0.1:8188",
        "COMFYUI_WORKFLOWS_DIR": "/path/hh-mcp-comfyui/workflows"
      }
    }
  }
}

贡献

  1. Fork项目

  2. 创建特性分支 (git checkout -b feature/AmazingFeature)

  3. 提交更改 (git commit -m 'Add some AmazingFeature')

  4. 推送到分支 (git push origin feature/AmazingFeature)

  5. 打开Pull Request

如有问题可以到公众号中联系我：

公众号二维码

Available Tools

2 tools
generate_image_from_imageA
Generates an image using ComfyUI based on an input image (URL, local path, or bytes), prompt, and optional parameters.

Args:
    prompt: The positive text prompt (It must be in English).
    workflow_name: The name of the I2I workflow file (without .json) to use (default: 'I2Image_bizyair_flux').
    image_path_or_url: The URL or local file path or image data as bytes of the input image.
    denoise: Denoising strength (0.0 to 1.0). Controls how much the original image influences the result. to use (default: '1.0')
    seed: Optional random seed for reproducibility.
Returns:
    A URL to view the generated image or an error message.
ParametersJSON Schema
NameRequiredDescriptionDefault
promptYes
workflow_nameYes
image_path_or_urlYesURL, local path, or image data as bytes.
denoiseNo
seedNo

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose behavioral traits like whether the tool is destructive, requires authentication, or handles errors. It only mentions returns a URL or error message, lacking deeper transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with an Args section, but could be more concise. Every sentence conveys necessary information, though the inclusion of default values could be streamlined.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 5 parameters, 3 required, no output schema, and no annotations, the description covers the parameters and return value adequately. However, it lacks details on error handling, constraints, or execution behavior, making it slightly incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With only 20% schema description coverage, the description compensates by explaining parameter details: prompt must be in English, workflow_name default and file extension, denoise range and effect, and seed optional. This adds value beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates an image using ComfyUI based on an input image, prompt, and optional parameters. This distinguishes it from the sibling tool 'generate_image_from_text' which presumably uses a text-only input.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description implies usage when an input image is available, but does not explicitly state when to use it vs. the sibling tool or any conditions/alternatives. No guidance on when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_image_from_textA
Generates an image using ComfyUI based on the provided prompt and optional parameters.

Args:
    prompt: The positive text prompt (It must be in English).
    workflow_name: The name of the workflow file (without .json) from the 'workflows' directory to use.
                If None, uses the default workflow ('t2image_bizyair_flux').
    width: The desired width of the image (default: 1024).
    height: The desired height of the image (default: 1024).
Returns:
    A URL to view the generated image.
ParametersJSON Schema
NameRequiredDescriptionDefault
promptYes
workflow_nameYes
widthNo
heightNo
seedNo

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It mentions the prompt must be in English, defaults for dimensions, and returns a URL. However, it does not disclose side effects, authentication needs, rate limits, or what happens on failure. It is adequate but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one paragraph with clear Args and Returns sections. It is concise but could be slightly more streamlined. No unnecessary information, and the structure helps parsing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, no annotations, and 0% schema coverage, the description is moderately complete. It covers most parameters and the return value, but lacks usage guidance and deeper behavioral context. Additional details on seed and error handling would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains prompt, workflow_name, width, and height, but fails to describe the 'seed' parameter, which is present in the schema but absent from the description. This omission reduces clarity for that parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it generates an image from a text prompt using ComfyUI. The verb 'Generates' and resource 'image' are specific, and the sibling tool 'generate_image_from_image' implies this is for text-to-image, distinguishing it effectively.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus the sibling. The description lists parameters but does not provide context for selection, such as specifying that this is for text-to-image while the sibling is for image-to-image. Usage is implied but not stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedgenerate_image_from_image
    • First observedgenerate_image_from_text
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.8/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: one takes an input image for image-to-image generation, the other takes a text prompt for text-to-image generation. An agent can easily select the appropriate tool based on whether they have a reference image.

Naming Consistency5/5

Both tool names follow a consistent 'generate_image_from_<source>' pattern (image vs text). The naming is uniform and predictable, making it easy for an agent to infer the function.

Tool Count4/5

With only 2 tools, the server is very focused but slightly sparse for a general ComfyUI interface. It covers the two fundamental generation modes, which is reasonable for a minimal setup, though a few more tools (e.g., upscale or inpaint) would be expected.

Completeness3/5

The server covers the two core ComfyUI workflows (text-to-image and image-to-image), but lacks common operations like upscaling, inpainting, or workflow management. There are notable gaps that agents cannot work around.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers