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
pip install -r requirements.txt

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 test_client.py

# Or provide your own prompt
python test_client.py -p "a beautiful sunset over mountains"
python 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: 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

... View full README on GitHub