ComfyUI MCP Skills

让 AI Agent 以原生 MCP 工具安全地理解、执行和管理 ComfyUI。

ComfyUI MCP Skills 把 ComfyUI 工作流、作业、资产和控制平面投影为结构化 MCP Tools、Resources 与 Prompts。Agent 无需拼接 Shell 命令，也无需直接修改工作流 JSON，即可完成工作流发现、参数校验、执行、结果复用、诊断、实验和受控运维。

项目当前版本为 1.1.0（正式发布）。包元数据要求 Python >=3.10；CI 已验证 3.10–3.13，更新版本尚未纳入验证矩阵。

本项目不是 ComfyUI 自定义节点。它是独立运行的 MCP 服务，通过 HTTP 和 WebSocket 连接一个或多个 ComfyUI 实例。

文档

• 安装与客户端配置

• 功能与使用模型

• 本地轻量引导（装配分层与 5 分钟上手）

• CLI → MCP 迁移方案

• Agent 原生控制平面设计

核心能力

工作流、Revision、Plan、Job 和 Asset 的高级能力依赖对应 SQLite aggregate cutover。全新目录默认先使用兼容文件仓库；执行本教程只保证基础工作流发现、动态执行、上传和 job.get 查询，不能把高级控制平面能力当作已自动启用。job.list（历史分页）只在 SQLite run cutover 后挂载。

完整工具面和使用流程见功能文档。

架构

flowchart LR
    Agent[AI Agent / MCP Host] -->|stdio 或 Streamable HTTP| Adapter[MCP Adapter]
    Adapter --> Auth[Toolset 与 Scope 授权]
    Adapter --> App[Application Services]
    App --> Store[(SQLite Control Plane)]
    App --> Gateway[ComfyUI Gateway]
    Gateway -->|HTTP / WebSocket| ComfyUI[ComfyUI Server]
    App --> Resources[MCP Resources / Prompts / Events]

依赖方向固定为：

MCP / HTTP / CLI adapters
            ↓
    Application services
            ↓
      Domain contracts
            ↑
 Infrastructure implementations

CLI 与 MCP 共用业务服务、ComfyUI Gateway 和持久化层；MCP handler 不启动 CLI 子进程。

快速安装

comfyui-mcp-skills 1.1.0 已进入正式发布流程（渠道与流程见 docs/RELEASING.zh-CN.md；PyPI 可见前请从 GitHub 安装或使用源码运行）。

方式一：从 GitHub 安装

python -m pip install "git+https://github.com/ShiroEirin/ComfyUI_MCP_Skills.git@main"

方式二：源码开发安装

git clone https://github.com/ShiroEirin/ComfyUI_MCP_Skills.git
cd ComfyUI_MCP_Skills
uv sync --locked --extra dev

安装后主要入口：

最小项目配置

MCP 数据目录至少需要 config.json 和工作流目录：

my-comfyui-mcp/
├── config.json
├── data/
│   └── local/
│       └── txt2img/
│           ├── schema.json
│           └── workflow.json
└── uploads/

config.json 示例：

{
  "default_server": "local",
  "servers": [
    {
      "id": "local",
      "name": "Local ComfyUI",
      "url": "http://127.0.0.1:8188",
      "enabled": true
    }
  ]
}

最小 MCP 客户端配置

源码运行配置：

{
  "mcpServers": {
    "comfyui": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "D:/github/ComfyUI_MCP_Skills",
        "comfyui-mcp"
      ],
      "env": {
        "COMFYUI_MCP_DIR": "D:/path/to/my-comfyui-mcp"
      }
    }
  }
}

已安装命令时，可改为：

{
  "mcpServers": {
    "comfyui": {
      "command": "comfyui-mcp",
      "env": {
        "COMFYUI_MCP_DIR": "D:/path/to/my-comfyui-mcp"
      }
    }
  }
}

Snow、Claude Code 或部分 OpenAI/Anthropic 兼容网关只接受 [A-Za-z0-9_-]+ 工具名。遇到 Invalid tools[n].name 时启用兼容模式：

{
  "env": {
    "COMFYUI_MCP_DIR": "D:/path/to/my-comfyui-mcp",
    "COMFYUI_MCP_PORTABLE_TOOL_NAMES": "1"
  }
}

启用后，外部名称从 comfyui.job.get 变为 comfyui_job_get，服务内部仍按 canonical 名称分发。OMP 等支持点号名称的 Host 无需启用。

完整的 Windows、Linux、Snow、Claude Code、权限和 HTTP 配置见安装教程。

默认安全模型

stdio 默认使用：

principal: local-stdio
toolset: execution
scope: comfyui:execute

因此默认只暴露执行所需能力。Authoring、Operations 和 Admin 必须显式配置 Toolset、Scope，并为高风险 Toolset 设置 COMFYUI_MCP_ENABLE_HIGH_RISK=1。

危险写操作遵循以下约束：

• 普通执行面与 Admin 管理面分离。

• 变更、安装、删除和全局操作优先采用 plan/commit。

• plan digest、幂等键、主体和对象所有权共同约束 commit。

• 作业取消不会调用 ComfyUI 的全局 /interrupt。

• runtime.restart.plan 提供影响快照与单次审批；runtime.restart.commit 在审批后执行固定 controller 命令（systemd/docker/windows_service 适配器），期间 /prompt 提交被 drain/fence 拒绝（SQLite run store 门控；文件后端/fresh 只读预览）。

• 远程上传、抓取、Host、Origin、正文大小、并发和速率均有边界。

基本使用流程

1. MCP Host 调用 comfyui.capability.search 查找当前授权能力。

2. Agent 选择 comfyui.run.<server>.<workflow>，参数由工作流 JSON Schema 校验。

3. 服务返回完成结果，或返回持久化 Job 标识供 comfyui.job.get 恢复查询。

4. 输出以 Resource Link 暴露，可作为后续 image、mask、audio 或 video 输入。

5. 失败时调用诊断与 retry plan/commit，而不是猜测并重复提交。

动态工具的 _execution 示例：

{
  "prompt": "a cinematic portrait",
  "_execution": {
    "idempotency_key": "portrait-2026-08-05-01",
    "wait": true,
    "wait_timeout_seconds": 120
  }
}

超时不代表作业失败，也不会丢失作业。继续使用返回的 Job 或 prompt_id 查询即可。

Streamable HTTP

远程模式拒绝匿名启动，支持：

• static：部署方配置的静态 Bearer Token。

• introspection：受众绑定的 RFC 7662 Token Introspection；端点必须为 HTTPS。

公网部署必须由反向代理终止 TLS。默认 process 限流模式拒绝 workers > 1；设置 COMFYUI_MCP_LIMIT_MODE=external 后使用 SQLite 共享限流后端，支持多 worker 的全局请求、并发与订阅配额。跨主机事件 fan-out 仍未交付。

详细环境变量和部署示例见安装教程。

开发与验证

uv sync --locked --extra dev
uv run ruff check src/comfyui_mcp_skills tests
uv run mypy src/comfyui_mcp_skills
uv run pytest -q
uv build

当前本地交付验证：1036 passed, 1 skipped, 2 subtests passed（含 otel extra 下的 OpenTelemetry 集成测试——SDK traces/metrics 与 logs 桥接均真实执行；未安装 otel extra 的环境对应为 1029 passed, 8 skipped——6 个 SDK 集成测试、1 个 logs 桥接集成测试与 1 个 Windows 符号链接用例跳过）。这表示代码与 contract harness 通过，不等于任意新数据目录已经完成所有 aggregate cutover。CI 在 Windows 与 Ubuntu 上覆盖 Python 3.10–3.13。

项目状态与边界

已实现可靠执行、版本化工作流（含高层 recipe：upscale_image/save_image/lora_model/controlnet_apply.v1）、资产血缘、Experiment、诊断恢复、供应编排、多服务器路由、显式运行时控制（审批式重启闭环 + systemd/Docker/Windows Service 控制器）、RFC 7662 introspection、审计闭环（append-only 事件 + 有界导出）与可选 OpenTelemetry traces/metrics/logs（工具调用 span、计数与耗时直方图、logging 记录导出到 /v1/logs，COMFYUI_MCP_OTEL_ENDPOINT base URL 配置，otel extra 安装，见安装文档第 11 章）。workflow aggregate cutover 后，file-backed 的 comfyui.admin.workflow.set_enabled/delete 不再挂载（审计工具仍可用）。以下能力尚未作为正式产品能力交付：

• Redis/NATS 多副本订阅总线。

• 多主机共享租约与跨主机配额（SQLite 共享限流仅限同主机多进程）。

• Dependency Provisioning 需要维护者提供 dependency-catalog.json，否则只可检查而不能解析安装来源。

• MCP Tasks 扩展映射。

• MCP Elicitation 审批。

本地单机部署边界

以下能力直接 proxy 引擎公共 API，不依赖控制平面存储：queue.list→/queue、server.health→/system_stats、node.list/describe→/object_info、model.list→/models、template.list/subgraph.list→/userdata、动态 run_*→/prompt、asset.upload→/upload。执行记录（job.*、幂等、Artifact 聚合、诊断/重试 lineage）是持久执行层而非引擎历史缓存——引擎 /history 只保留运行中/近期记录且引擎重启即失，因此 job.list 不退化为引擎历史 proxy。comfyui.local.plugins（本地会话）从 server 条目配置的 local_root 读取 custom_nodes 插件清单（双布局兼容 aki 的 ComfyUI/custom_nodes 与标准 custom_nodes，有界扫描 + reparse/symlink 拒绝 + TOCTOU 复核）；云端/未配置会话返回 available:false 固定原因码。aki 等第三方整合包接入示例：

{
  "servers": [
    {
      "id": "aki",
      "name": "Aki ComfyUI",
      "url": "http://127.0.0.1:8188",
      "local_root": "D:\\ConfyUI-aki\\ComfyUI-aki-v1.6"
    }
  ]
}

本地 vs 云端节点信息策略：本地会话 = local.plugins（插件级能力）+ node.blueprint/list/describe（API 节点级）；云端会话 = 仅 API 节点级（local.plugins 明确降级）。comfyui.workflow.visualize：已发布工作流有界 Mermaid 渲染（≤50 节点，SQLite Workflow store 门控）；revision.diff 输出含 mermaid 视图（added 节点高亮），change.plan 的 diff 不含。comfyui.model.guidance：社区共识的模型家族采样器/调度器/steps/CFG/分辨率起点（9 个家族，静态数据，非引擎保证）。comfyui.job.history.suggest：基于本地运行历史的证据驱动参数建议（SQLite run store 门控、256 截断、仅本 principal 面可见）。本地查看跑图历史的最短路径是直接查询引擎 GET /history，或使用 CLI history 命令读取本地 data/ 目录；独立的只读引擎历史工具 comfyui.engine.history 已交付（扁平投影 prompt_id/status/outputs_count，8 MiB 有界解码，limit ≤50），避免污染 job.list 的 owner-bound 持久记录契约。控制平面按装配分层初始化：fresh 数据目录（无 data/control-plane.sqlite3）走轻量路径不建控制平面数据库，既有数据库完整初始化与升级；分层说明与本地 5 分钟上手见轻量引导文档。

持久化 schema 自 1.1.0 起版本化冻结：已发布迁移不可改写（改动在初始化时被拒绝，跨版本升级由迁移回归套件验证，覆盖 v1–v13 → 当前）；升级自动应用且单向——新版本保证打开并升级任一已冻结历史前缀，新 schema 被旧版本代码打开时显式拒绝（fail-loud，不承诺降级），降级只能通过升级前备份恢复。升级前仍建议备份 config.json、data/ 和控制平面数据库。

License

MIT