Grow images from typed code.

A fully typed client for your ComfyUI server: tweak workflows, stream progress and preview frames, spread jobs across GPUs. And one command hands the same server to Claude Code, Codex or Cursor.

For your app

npm install comfyui-node

For your agent

npx -y comfyui-node

TypeScript SDK + MCP server · v1.12.0 · tracks ComfyUI v0.44 · Node 22+ and Bun · MIT

Pressed red and violet seaweed fronds on black archival paper, rendered by comfyui-node with seed 20251

Rhodophyta, seed 20251

Seed
Sampler
const job = await api.run(
  Workflow.from(krea2Turbo)
    .set('56.inputs.seed', 20251)
    .set('56.inputs.sampler_name', 'euler'));
job.on('preview', show);  // every step, live

Acc. 0001krea2_turbo · 8 steps · 832 × 1024 2.8 s on RTX PRO 6000 Blackwell

  1. noise
  2. step 2
  3. step 4
  4. step 6
  5. step 8

Plate I · Rhodophyta, three seeds, two samplers

Two ways in.

The same package is a library you import and a server your agent runs. Both talk only to the ComfyUI URL you give them.

Tweak a saved workflow, run it, read the outputs.

import { ComfyApi, Workflow } from 'comfyui-node';
import base from './txt2img.json';

const api = await new ComfyApi('http://127.0.0.1:8188').ready();

const wf = Workflow.from(base)
  .set('6.inputs.text', 'A dramatic cinematic landscape')
  .set('3.inputs.seed', -1)     // randomized for you
  .output('images:9');

const job = await api.run(wf, { autoDestroy: true });
job.on('progress_pct', (pct) => console.log(`${pct}%`));

const result = await job.done();
for (const img of result.images.images) {
  console.log(api.ext.file.getPathImage(img));
}
Workflow.from
Dot-path .set(), named output aliases, .attachImage(), and deterministic structure hashing
api.run(wf)
Streams progress_pct, preview, and preview_meta frames, with automatic /history recovery
PromptBuilder
Typed input/output keys when reusable graphs outgrow raw node numbers
WorkflowPool
Multi-GPU job queue with health checks, node profiling, timeouts, and smart failover

Acc. 0002 · In your app (TypeScript SDK) Getting started · Workflow guide

Let your coding agent build, run and review workflows.

claude mcp add comfyui -- npx -y comfyui-node \
  --url http://127.0.0.1:8188 --workflow-dir ./workflows
comfy_info
Reachability, GPU and RAM, queue, installed models, runnable recipes
comfy_nodes
Search installed nodes and read exact pin schemas
comfy_recipes
Scaffold a ready-to-run graph for the models you have
comfy_validate
Check wiring and types against live node definitions
comfy_workflows
List, save and delete stored workflows and their slots
comfy_generate
Run with overrides, candidate count, seed policy, attachments
comfy_inspect
Contact sheets, single images, crops, before and after
comfy_revise
Branch a new run from a previous one, keeping lineage
comfy_job
Check, wait on, or cancel a run

Acc. 0003 · In your agent (MCP stdio) AI agent guide · Compare with comfy-mcp

How the bundled MCP server compares with Comfy-Org/comfy-mcp.

Comfy-Org’s official local MCP server wraps comfy-cli in Python to manage and run a local ComfyUI installation. comfyui-node takes a direct, in-process TypeScript path built around a compact 9-tool surface, inline visual contact sheets, and recorded seed lineage.

Architectural comparison · full breakdown in the AI agent guide
Dimension comfyui-node MCP (npx -y comfyui-node) Official Comfy-Org/comfy-mcp
Runtime & setup Node 22+ or Bun · single npx -y comfyui-node command, zero Python setup; ships inside the SDK package Python 3.10+ · pip install comfy-mcp "comfy-cli>=1.14"
ComfyUI transport In-process HTTP + WebSocket (ComfyApi) · persistent socket, live notifications/progress, automatic /history recovery CLI subprocess wrapper · each tool call spawns comfy --where local --json … and parses the CLI output
Tool surface 9 focused tools · compact, deterministic tool-schema footprint; node and model catalogs queried on demand ~40 CLI-passthrough tools · generation, discovery, workflow slots, plus host process & package management
Visual review & lineage Inline sharp vision pipeline · labeled contact sheets, region crops, side-by-side parent/child diffs, and comfy_revise with parentRunId lineage comfy-cli media tools · video contact sheets, audio waveforms, and output file harvesting
Host lifecycle vs. app reuse Scoped to workflows & runs · the exact graphs your agent builds run unchanged in TypeScript on ComfyApi and WorkflowPool Full host administration · can start/stop/restart ComfyUI, pull models, and run install_node via comfy-cli
License MIT AGPL-3.0-or-later / commercial dual license

Plate II · two front doors, one library

Watch it develop.

ComfyUI streams a preview frame at every sampling step. comfyui-node decodes each one straight off the WebSocket, with its node and prompt metadata, so you can show the image forming instead of a spinner.

Pressed seaweed on black paper, seed 77115, shown at the selected sampling step
const job = await api.run(wf);

job.on('progress_pct', (pct) => bar.value = pct);
job.on('preview_meta', ({ blob, metadata }) => {
  // metadata.node_id === '56', the KSampler
  frame.src = URL.createObjectURL(blob);
});

Acc. 0003-B · seed 77115euler · beta578 steps, 8 preview frames · 2.9 s end to end

Plate III · one render, five states

Seeds, kept and revised.

Ask an agent for four candidates and it gets four real renders and a contact sheet to judge them. Ask for a revision and it branches a child run from the parent, same seed, with the lineage recorded.

Coleoptera · Buprestidae — four sequential seeds (5100–5103) rendered in one comfy_generate call. The model holds the species; the seed varies the specimen. Hover or tap any plate to develop its full colour.

{ workflow: krea2Turbo, count: 4,
  seed: 5100, seedPolicy: 'sequential' }

Acc. 0004 · MCP comfy_generate4 candidates · 9.4 s for the set

{ runId: 'run_…9187fb80',
  seedPolicy: 'keep',
  prompt: '…cold blue moonlight, deep shadows',
  note: 'Same shell, same seed: swap warm'
      + ' tungsten for cold moonlight' }

Acc. 0005 · MCP comfy_reviseparentRunId recorded · seed kept: 2718

Plate IV · one beetle in four seeds, one shell revised · hover or tap a specimen to develop it

One job, many GPUs.

WorkflowPool spreads jobs across ComfyUI instances with health checks, per-node profiling, timeouts and failover that blocks a workflow on a host, not the host. MultiWorkflowPool goes further: register a different variant of the same render per host, and it runs the one whose host is free.

One logical render (Adiantum, seed 4210), a distinct workflow variant per GPU
HostVariantStructure hashState
blackwell:8188krea2_turbo · nvfp40247…1abarendered · 3.1 s
ampere:8188z_image_turbo · nvfp44f65…a8f1idle → takes job 42
studio:8188general queue—health check ok
  • SmartFailoverStrategy cools a workflow down on the host that failed it, and keeps routing it elsewhere.
  • executionStartTimeoutMs and nodeExecutionTimeoutMs catch stuck servers and nodes.
  • enableProfiling returns per-node timings and the slowest nodes for every job.
  • completedJobRetention keeps long-running pools at a bounded memory footprint.
const krea2  = Workflow.from(graphKrea2).updateHash();  // 0247…1aba
const zImage = Workflow.from(graphZImage).updateHash(); // 4f65…a8f1

pool.addClient('http://blackwell:8188', { workflowAffinity: [krea2] });
pool.addClient('http://ampere:8188',    { workflowAffinity: [zImage] });
await pool.init();

// runs on whichever host is free, with that host's own variant
const id = await pool.submitToVariants([krea2, zImage]);
const out = await pool.waitForJobCompletion(id);

Acc. 0006 · MultiWorkflowPool.submitToVariantsseed 4210 · two architectures, one logical job

Plate V · WorkflowPool · hash-based routing

The register.

Everything on api.ext, typed and current with ComfyUI v0.44, plus every guide.

api.ext

  1. E-01queueQueue prompts with your own prompt id, partial execution targets and workflow metadata
  2. E-02jobsList jobs, and cancel any of them whether running or pending
  3. E-03historyRead, page, delete and clear prompt history
  4. E-04nodeNode definitions (V1 and V3 COMBO), checkpoints, LoRAs, samplers, replacements
  5. E-05modelModel folders, files and safetensors metadata
  6. E-06fileUpload images and masks, /view previews, user data v1 and v2
  7. E-07assetsList, upload, tag, download, seed and prune assets
  8. E-08systemSystem stats and freeing VRAM
  9. E-09miscEmbeddings, extensions, global subgraphs, workflow templates, i18n
  10. E-10featureFlagsServer feature flags, negotiated on connect
  11. E-11monitorSystem monitor events (Crystools)
  12. E-12terminalServer logs and log subscription
  13. E-13userUser config and settings
  14. E-14managerComfyUI-Manager custom node management

Guides

  1. G-01Getting started
  2. G-02Workflow guide
  3. G-03AI agent guide (MCP)
  4. G-04WorkflowPool
  5. G-05Hash-based routing
  6. G-08Execution timeouts
  7. G-09Profiling
  8. G-11Event-based logging
  9. G-12Troubleshooting
  10. G-14Migration guide

The full register of guides