ComfyUI MCP Server

Generate and refine AI images/audio/video through natural conversation

A lightweight MCP (Model Context Protocol) server that lets AI agents generate and iteratively refine images, audio, and video using a local ComfyUI instance.

You run the server, connect a client, and issue tool calls. Everything else is optional depth.

Quick Start (2–3 minutes)

This proves everything is working.

1) Clone and set up

git clone https://github.com/joenorton/comfyui-mcp-server.git
cd comfyui-mcp-server
uv sync

2) Start ComfyUI

Make sure ComfyUI is installed and running locally.

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

3) Run the MCP server

From the repository directory:

python server.py

The server listens at:

http://127.0.0.1:9000/mcp

4) Verify it works (no AI client required)

Run the included test client:

# Use default prompt
python tests/clients/test_client.py

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

test_client.py will:

connect to the MCP server
list available tools
fetch and display server defaults (width, height, steps, model, etc.)
run generate_image with your prompt (or a default)
automatically use server defaults for all other parameters
print the resulting asset information

If this step succeeds, the system is working.

Note: The test client respects server defaults configured via config files, environment variables, or set_defaults calls. Only the prompt parameter is required; all other parameters use server defaults automatically.

That’s it.

Use with an AI Agent (Cursor / Claude / n8n)

Once the server is running, you can connect it to an AI client.

Create a project-scoped .mcp.json file:

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

Note for WSL Users: If you are running Cursor on Windows and the server inside WSL, use the streamable-http method above with the server running in your WSL terminal. Alternatively, for stdio mode, use wsl as the command:

"comfyui": {
  "type": "stdio",
  "command": "wsl",
  "args": [
    "env",
    "PYTHONPATH=/path/to/your/src",
    "/home/user/.local/bin/uv",
    "--directory",
    "/path/to/your/project",
    "run",
    "server.py",
    "--stdio"
  ]
}

Note: Some clients use "type": "http" instead of "streamable-http". Both work with this server. If auto-discovery doesn't work, try changing the type field.

Restart your AI client. You can now call tools such as:

generate_image
view_image
regenerate
get_job
list_assets

This is the primary intended usage mode.

What You Can Do After It Works

Once you’ve confirmed the server runs and a client can connect, the system supports:

Iterative refinement via regenerate (no re-prompting)
Explicit asset identity for reliable follow-ups
Job polling and cancellation for long-running generations
Optional image injection into the AI’s context (view_image)
Auto-discovered ComfyUI workflows with parameter exposure
Configurable defaults to avoid repeating common settings

Everything below builds on the same basic loop you just tested.

Migration Notes (Previous Versions)

If you’ve used earlier versions of this project, a few things have changed.

What’s the Same

You still run a local MCP server that delegates execution to ComfyUI
Workflows are still JSON files placed in the workflows/ directory
Image generation behavior is unchanged at its core

What’s New

Streamable HTTP transport replaces the older WebSocket-based approach
Explicit job management (get_job, get_queue_status, cancel_job)
Asset identity instead of ad-hoc URLs (stable across hostname changes)
Iteration support via regenerate (replay with parameter overrides)
Optional visual feedback for agents via view_image
Configurable defaults to avoid repeating common parameters

What Changed Conceptually

Earlier versions were a thin request/response bridge. The current version is built around iteration and stateful control loops.

You can still generate an image with a single call, but you now have the option to:

refer back to specific outputs
refine results without re-specifying everything
poll and cancel long-running jobs
let AI agents inspect generated images directly

Looking for the Old Behavior?

If you want the minimal, single-shot behavior from earlier versions:

run tests/clients/test_client.py (this mirrors the original usage pattern)
call generate_image with just a prompt (server defaults handle the rest)
ignore the additional tools

No migration is required unless you want the new capabilities.

Available Tools

Generation Tools

generate_image: Generate images (requires prompt)
generate_song: Generate audio (requires tags and lyrics)
regenerate: Regenerate an existing asset with optional parameter overrides (requires asset_id)

Viewing Tools

view_image: View generated images inline (images only, not audio/video)

Job Management Tools

get_queue_status: Check ComfyUI queue state (running/pending jobs) - provides async awareness
get_job: Poll job completion status by prompt_id - check if a job has finished
list_assets: Browse recently generated assets - enables AI memory and iteration
get_asset_metadata: Get full provenance and parameters for an asset - includes workflow history
cancel_job: Cancel a queued or running job

Configuration Tools

list_models: List available ComfyUI models
get_defaults: Get current default values
set_defaults: Set default values (with optional persistence)

Node Introspection Tools

Purpose: Enable AI agents to understand, troubleshoot, and build ComfyUI workflows. When a user provides a workflow JSON, agents can use these tools to validate node configurations, discover compatible nodes, and intelligently extend or fix workflows.

list_available_nodes: List all ComfyUI nodes with categories and metadata - discover what's available in the environment
get_node_definition: Get detailed schema for a specific node (inputs, outputs, types) - validate and understand node requirements
search_nodes: Search for nodes by name, category, or output type - find compatible nodes for workflow construction
get_node_inputs: Get input parameter specifications for a node - troubleshoot missing or incorrect parameters

Common Use Cases:

Troubleshooting: User provides broken workflow → agent uses get_node_definition to validate node inputs and identify issues
Extension: User wants to add upscaling → agent uses search_nodes(output_type="IMAGE") to find compatible nodes
Building: User describes desired workflow → agent uses list_available_nodes and search_nodes to construct workflow from scratch

Workflow Tools

list_workflows: List all available workflows
run_workflow: Run any workflow with custom parameters

Publish Tools

get_publish_info: Show publish status (detected project root, publish dir, ComfyUI output root, and any missing setup)
set_comfyui_output_root: Set ComfyUI output directory (recommended for Comfy Desktop / nonstandard installs; persisted across restarts)
publish_asset: Publish a generated asset into the project's web directory with deterministic compression (default 600KB)

Publish Notes:

Session-scoped: asset_ids are valid only for the current server session; restart invalidates them.
Zero-config in common cases: Publish dir auto-detected (public/gen, static/gen, or assets/gen); if ComfyUI output can't be detected, set it once via set_comfyui_output_root.
Two modes: Demo (explicit filename) and Library (auto filename + manifest update). In library mode, manifest_key is required.
Manifest: Updated only when manifest_key is provided.
Compression: Deterministic ladder to meet size limits; fails with a clear error if it can't.

Quick Start:

Example agent conversation flow:

User: "Generate a hero image for my website and publish it as hero.webp"

Agent: Checks publish configuration

Calls get_publish_info() → sees status "ready"

Agent: Generates image

Calls generate_image(prompt="a hero image for a website") → gets asset_id

Agent: Publishes asset

Calls publish_asset(asset_id="...", target_filename="hero.webp") → success

User: "Now generate a logo and add it to the manifest as 'site-logo'"

Agent: Generates and publishes with manifest

Calls generate_image(prompt="a modern logo") → gets asset_id
Calls publish_asset(asset_id="...", manifest_key="site-logo") → auto-generates filename, updates manifest

See docs/HOW_TO_TEST_PUBLISH.md for detailed usage and testing instructions.

Custom Workflows

Add custom workflows by placing JSON files in the workflows/ directory. Workflows are automatically discovered and exposed as MCP tools.

Workflow Placeholders

Use PARAM_* placeholders in workflow JSON to expose parameters:

PARAM_PROMPT → prompt: str (required)
PARAM_INT_STEPS → steps: int (optional)
PARAM_FLOAT_CFG → cfg: float (optional)

Example:

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

The tool name is derived from the filename (e.g., my_workflow.json → my_workflow tool).

Configuration

The server supports configurable defaults to avoid repeating common parameters. Defaults can be set via:

Runtime defaults: Use set_defaults tool (ephemeral, lost on restart)
Config file: ~/.config/comfy-mcp/config.json (persistent)
Environment variables: COMFY_MCP_DEFAULT_* prefixed variables

Defaults are resolved in priority order: per-call values → runtime defaults → config file → environment variables → hardcoded defaults.

For complete configuration details, see docs/REFERENCE.md.

Detailed Reference

Complete parameter lists, return schemas, configuration options, and advanced workflow metadata are documented in:

API Reference - Complete tool reference, parameters, return values, and configuration
Architecture - Design decisions and system overview

Project Structure

comfyui-mcp-server/
├── server.py              # Main entry point
├── src/                   # Source code
│   ├── auth/              # Authentication abstractions
│   ├── client/            # HTTP client with httpx
│   ├── routes/            # HTTP transport layer
│   ├── orchestrators/     # Business logic layer
│   ├── models/            # Data models
│   ├── tools/             # MCP tool registrations
│   └── utils/             # Cross-cutting utilities
│       └── asset_processor.py  # Image processing
├── tests/                 # Test files
│   └── clients/
│       └── test_client.py # Test client
├── docs/                  # Documentation
└── workflows/             # Workflow JSON files
    ├── generate_image.json
    └── generate_song.json

Notes

The server binds to localhost by default. Do not expose it publicly without authentication or a reverse proxy.
Ensure your models exist in <ComfyUI_dir>/models/checkpoints/
Server uses streamable-http transport (HTTP-based, not WebSocket)
Workflows are auto-discovered - no code changes needed
Assets expire after 24 hours (configurable)
view_image only supports images (PNG, JPEG, WebP, GIF)
Asset identity uses (filename, subfolder, type) instead of URL for robustness
Full workflow history is stored for provenance and reproducibility
regenerate uses stored workflow data to recreate assets with parameter overrides
Session isolation: list_assets can filter by session for clean AI agent context

Troubleshooting

Server won't start:

Check ComfyUI is running on port 8188 (default)
Verify Python 3.8+ is installed (python --version)
Check all dependencies are installed: pip install -r requirements.txt
Check server logs for specific error messages

Client can't connect:

Verify server shows "Server running at http://127.0.0.1:9000/mcp" in the console
Test server directly: curl http://127.0.0.1:9000/mcp (should return MCP response)
Check .mcp.json is in project root (or correct location for your client)
Try both "type": "streamable-http" and "type": "http" - both are supported
For Cursor-specific issues, see docs/MCP_CONFIG_README.md

Tools not appearing:

Check workflows/ directory has JSON files with PARAM_* placeholders
Check server logs for workflow parsing errors
Verify ComfyUI has required custom nodes installed (if using custom workflows)
Restart the MCP server after adding new workflows

Asset not found errors:

Assets expire after 24 hours by default (configurable via COMFY_MCP_ASSET_TTL_HOURS)
Assets are lost on server restart (ephemeral by design)
Use get_asset_metadata to verify asset exists before using regenerate
Check server logs to see if asset was registered successfully

Known Limitations (v1.0)

Ephemeral asset registry: asset_id references are only valid while the MCP server is running (and until TTL expiry). After restart, previously-issued asset_ids can’t be resolved, and regenerate will fail for those assets.

Contributing

Issues and pull requests are welcome! See CONTRIBUTING.md for development guidelines.

Acknowledgements

@venetanji - streamable-http foundation & PARAM_* system

Maintainer

@joenorton

License

Apache License 2.0