comfyui mcp server

a lightweight python-based mcp (model context protocol) server that interfaces with a local comfyui instance to generate images programmatically via ai agent requests.

overview

this project enables ai agents to send image generation requests to comfyui using the mcp protocol over websocket. it supports:

• flexible workflow selection (e.g., basic_api_test.json).
• dynamic parameters: prompt, width, height, and model.
• returns image urls served by comfyui.

prerequisites

• python 3.10+
• comfyui: installed and running locally (e.g., on localhost:8188).
• dependencies: requests, websockets, mcp (install via pip).

setup

1. clone the repository: git clone cd comfyui-mcp-server

2. install dependencies:

   pip install requests websockets mcp

3. start comfyui:

• install comfyui (see comfyui docs).
• run it on port 8188:

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

4. prepare workflows:

• place api-format workflow files (e.g., basic_api_test.json) in the workflows/ directory.
• export workflows from comfyui’s ui with “save (api format)” (enable dev mode in settings).

usage

1. run the mcp server: python server.py

• listens on ws://localhost:9000.

2. test with the client: python client.py

• sends a sample request: "a dog wearing sunglasses" with 512x512 using sd_xl_base_1.0.safetensors.
• output example:

  response from server:
  {
    "image_url": "http://localhost:8188/view?filename=comfyui_00001_.png&subfolder=&type=output"
  }
  

3. custom requests:

• modify client.py’s payload to change prompt, width, height, workflow_id, or model.
• example:

  "params": json.dumps({
      "prompt": "a cat in space",
      "width": 768,
      "height": 768,
      "workflow_id": "basic_api_test",
      "model": "v1-5-pruned-emaonly.ckpt"
  })
  

project structure

• server.py: mcp server with websocket transport and lifecycle support.
• comfyui_client.py: interfaces with comfyui’s api, handles workflow queuing.
• client.py: test client for sending mcp requests.
• workflows/: directory for api-format workflow json files.

notes

• ensure your chosen model (e.g., v1-5-pruned-emaonly.ckpt) exists in <comfyui_dir>/models/checkpoints/.
• the mcp sdk lacks native websocket transport; this uses a custom implementation.
• for custom workflows, adjust node ids in comfyui_client.py’s default_mapping if needed.

contributing

feel free to submit issues or prs to enhance flexibility (e.g., dynamic node mapping, progress streaming).

license

apache license