comfyui-mcp-server

자연스러운 대화를 통해 AI 이미지/오디오/비디오를 생성하고 개선합니다.

AI 에이전트가 로컬 ComfyUI 인스턴스를 사용하여 이미지, 오디오, 비디오를 생성하고 반복적으로 개선할 수 있도록 하는 경량 MCP (Model Context Protocol) 서버입니다.

서버를 실행하고, 클라이언트를 연결한 뒤, 도구 호출 (tool calls)을 명령하면 됩니다. 그 외의 모든 것은 선택적인 심화 기능입니다.

이 과정은 모든 것이 정상적으로 작동함을 증명합니다.

git clone https://github.com/joenorton/comfyui-mcp-server.git
cd comfyui-mcp-server
pip install -r requirements.txt

ComfyUI가 로컬에 설치되어 실행 중인지 확인하십시오.

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

저장소 디렉토리에서:

python server.py

서버는 다음 주소에서 대기합니다:

포함된 테스트 클라이언트를 실행하십시오:

# 기본 프롬프트 사용
python test_client.py
# 또는 직접 프롬프트 제공
...

test_client.py는 다음을 수행합니다:

MCP 서버에 연결
사용 가능한 도구 (tools) 목록 표시
서버 기본값 (너비, 높이, 단계 (steps), 모델 등)을 가져와 표시
사용자의 프롬프트(또는 기본값)로 generate_image 실행 - 다른 모든 매개변수에는 서버 기본값을 자동으로 사용
결과물 에셋 (asset) 정보 출력

이 단계가 성공하면 시스템이 작동하는 것입니다.

참고: 테스트 클라이언트는 설정 파일, 환경 변수 또는 set_defaults 호출을 통해 구성된 서버 기본값을 준수합니다. prompt 매개변수만 필수이며, 다른 모든 매개변수는 서버 기본값을 자동으로 사용합니다.

이것으로 끝입니다.

서버가 실행되면 AI 클라이언트에 연결할 수 있습니다.

프로젝트 범위의 .mcp.json 파일을 생성하십시오:

{
"mcpServers": {
"comfyui-mcp-server": {
...

참고: 일부 클라이언트는 `

regenerate를 통한 반복적 개선 (재프롬프트 불필요) - 신뢰할 수 있는 후속 작업을 위한 명시적 에셋 식별 (Explicit asset identity)
장시간 실행되는 생성 작업을 위한 작업 폴링 (Job polling) 및 취소 기능
AI 컨텍스트로의 선택적 이미지 주입 (view_image)
파라미터 노출을 포함한 자동 검색된 ComfyUI 워크플로우 (Workflows)
공통 설정을 반복하지 않기 위한 구성 가능한 기본값 (Configurable defaults)

아래의 모든 내용은 방금 테스트한 것과 동일한 기본 루프를 기반으로 구축됩니다.

이 프로젝트의 이전 버전을 사용해 보셨다면, 몇 가지 변경 사항이 있습니다.

여전히 ComfyUI로 실행을 위임하는 로컬 MCP 서버를 실행합니다.
워크플로우는 여전히 workflows/ 디렉토리에 배치된 JSON 파일입니다.
이미지 생성 동작의 핵심은 변경되지 않았습니다.

스트리밍 가능한 HTTP 전송 (Streamable HTTP transport) 방식이 기존의 WebSocket 기반 방식을 대체합니다.
명시적 작업 관리 (Explicit job management) (get_job, get_queue_status, cancel_job)
에셋 식별 (Asset identity) 방식이 임시 URL 대신 사용됩니다 (호스트 이름 변경 시에도 안정적임).
반복 지원 (Iteration support) (regenerate를 통해 파라미터 재정의와 함께 재생).
선택적 시각적 피드백 (Optional visual feedback) (view_image를 통해 에이전트에게 제공).
구성 가능한 기본값 (Configurable defaults) (공통 파라미터 반복 방지).

이전 버전은 얇은 요청/응답 브리지(request/response bridge)였습니다.
현재 버전은 반복 (iteration) 및 **상태 유지 제어 루프 (stateful control loops)**를 중심으로 구축되었습니다.

여전히 단일 호출로 이미지를 생성할 수 있지만, 이제 다음과 같은 옵션을 사용할 수 있습니다:

특정 출력물을 다시 참조
모든 것을 다시 지정하지 않고 결과 개선
장시간 실행되는 작업을 폴링 및 취소
AI 에이전트가 생성된 이미지를 직접 검사하도록 허용

이전 버전의 최소한의 단발성(single-shot) 동작을 원하신다면:

test_client.py를 실행하십시오 (이는 원래의 사용 패턴을 반영합니다).
프롬프트만 사용하여 generate_image를 호출하십시오 (나머지는 서버 기본값이 처리합니다).
추가된 도구들은 무시하십시오.

새로운 기능을 사용하려는 것이 아니라면 마이그레이션은 필요하지 않습니다.

: 이미지 생성 (generate_image 필요, prompt 사용): 오디오 생성 (generate_song 필요, tags 및 lyrics 사용)

): 선택적 파라미터 오버라이드(parameter overrides)를 사용하여 기존 에셋을 재생성합니다 (regenerate 필요, asset_id 사용)

: 생성된 이미지를 인라인으로 확인합니다 (이미지만 가능, 오디오/비디오 제외) (view_image)

: ComfyUI 큐(queue) 상태(실행 중/대기 중인 작업)를 확인합니다 - 비동기 인지(async awareness)를 제공합니다 (get_queue_status)

: prompt_id를 통해 작업 완료 상태를 폴링(poll)합니다 - 작업이 완료되었는지 확인합니다 (get_job)

: 최근에 생성된 에셋을 탐색합니다 - AI 메모리 및 반복(iteration)을 가능하게 합니다 (list_assets)

: 에셋의 전체 출처(provenance) 및 파라미터를 가져옵니다 - 워크플로우 이력을 포함합니다 (get_asset_metadata)

: 대기 중이거나 실행 중인 작업을 취소합니다 (cancel_job)

: 사용 가능한 ComfyUI 모델 목록을 나열합니다 (list_models)

: 현재 기본값(default values)을 가져옵니다 (get_defaults)

: 기본값을 설정합니다 (선택적 영구 저장 가능) (set_defaults)

: 사용 가능한 모든 워크플로우를 나열합니다 (list_workflows)

: 사용자 정의 파라미터로 모든 워크플로우를 실행합니다 (run_workflow)

: 게시 상태를 표시합니다 (감지된 프로젝트 루트, 게시 디렉토리, ComfyUI 출력 루트 및 누락된 설정 확인) (get_publish_info)

: ComfyUI 출력 디렉토리를 설정합니다 (Comfy Desktop 또는 비표준 설치 시 권장됨; 재시작 후에도 유지됨) (set_comfyui_output_root)

: 결정론적 압축(deterministic compression, 기본 600KB)을 사용하여 생성된 에셋을 프로젝트의 웹 디렉토리에 게시합니다 (publish_asset)

게시 참고 사항 (Publish Notes):

세션 범위 (Session-scoped): asset_id는 현재 서버 세션에서만 유효하며, 재시작 시 무효화됩니다.
일반적인 경우 설정 불필요 (Zero-config): 게시 디렉토리가 자동으로 감지됩니다 (public/gen, static/gen 또는 assets/gen); ComfyUI 출력을 감지할 수 없는 경우 set_comfyui_output_root를 통해 한 번 설정하십시오.
두 가지 모드: 데모(Demo, 명시적 파일명) 및 라이브러리(Library, 자동 파일명 + 매니페스트 업데이트). 라이브러리 모드에서는 manifest_key가 필요합니다.
매니페스트 (Manifest): manifest_key가 제공될 때만 업데이트됩니다.
압축 (Compression): 크기 제한을 맞추기 위한 결정론적 계단식(deterministic ladder) 방식을 사용하며, 불가능할 경우 명확한 에러와 함께 실패합니다.

빠른 시작 (Quick Start):

에이전트 대화 흐름 예시:

사용자: "내 웹사이트를 위한 히어로 이미지를 생성하고 hero.webp로 게시해줘"

에이전트: 게시 설정 확인

get_publish_info() 호출

→ 상태 "ready" 확인

에이전트: 이미지 생성

generate_image(prompt="a hero image for a website") 호출

→ asset_id 획득

에이전트: 에셋 게시

publish_asset(asset_id="...", target_filename="hero.webp") 호출

→ 성공

사용자: "이제 로고를 생성하고 매니페스트(manifest)에 'site-logo'로 추가해줘"

에이전트: 매니페스트와 함께 생성 및 게시

generate_image(prompt="a modern logo") 호출

→ asset_id 획득

publish_asset(asset_id="...", manifest_key="site-logo") 호출

→ 파일명 자동 생성 및 매니페스트 업데이트

상세한 사용법 및 테스트 지침은 docs/HOW_TO_TEST_PUBLISH.md를 참조하세요.

workflows/ 디렉토리에 JSON 파일을 배치하여 커스텀 워크플로우 (workflows)를 추가할 수 있습니다. 워크플로우는 자동으로 검색되어 MCP 도구 (tools)로 노출됩니다.

워크플로우 JSON에서 PARAM_* 플레이스홀더 (placeholders)를 사용하여 파라미터 (parameters)를 노출할 수 있습니다:

PARAM_PROMPT → prompt: str (필수)
PARAM_INT_STEPS → steps: int (선택 사항)
PARAM_FLOAT_CFG → cfg: float (선택 사항)

예시:

{
"3": {
"inputs": {
...

도구 이름은 파일명에서 유도됩니다 (예: my_workflow.json → my_workflow 도구).

서버는 공통 파라미터를 반복하지 않도록 설정 가능한 기본값 (defaults)을 지원합니다. 기본값은 다음을 통해 설정할 수 있습니다:

런타임 기본값 (Runtime defaults): set_defaults 도구 사용 (휘발성, 재시작 시 소멸)
설정 파일 (Config file): ~/.config/comfy-mcp/config.json (지속성)
환경 변수 (Environment variables): COMFY_MCP_DEFAULT_* 접두사가 붙은 변수

기본값은 다음 우선순위 순으로 결정됩니다: 호출 시 값 → 런타임 기본값 → 설정 파일 → 환경 변수 → 하드코딩된 기본값.

전체 설정 세부 정보는 docs/REFERENCE.md를 참조하세요.

전체 파라미터 목록, 반환 스키마 (return schemas), 설정 옵션 및 고급 워크플로우 메타데이터 (metadata)는 다음 문서에 기록되어 있습니다:

API 레퍼런스 (API Reference) - 전체 도구 참조, 파라미터, 반환 값 및 설정
아키텍처 (Architecture) - 설계 결정 및 시스템 개요

comfyui-mcp-server/
├── server.py # 메인 엔트리 포인트 (Main entry point)
├── comfyui_client.py # ComfyUI API 클라이언트 (API client)
...

서버는 기본적으로 localhost에 바인딩됩니다. 인증이나 리버스 프록시 (reverse proxy) 없이 공개적으로 노출하지 마세요.
모델이 다음 경로에 존재하는지 확인하세요:
<ComfyUI_dir>/models/checkpoints/
서버는 다음을 사용합니다:
streamable-http 전송 방식 (HTTP 기반, WebSocket 아님) - 워크플로우 (Workflows)가 자동으로 검색되어 코드 변경이 필요 없습니다.
에셋 (Assets)은 24시간 후에 만료됩니다 (설정 가능).
view_image

이미지 (PNG, JPEG, WebP, GIF)만 지원합니다. 에셋 식별은 견고함을 위해 URL 대신
(filename, subfolder, type)
을 사용합니다. 출처 확인 (provenance) 및 재현성 (reproducibility)을 위해 전체 워크플로우 히스토리가 저장됩니다.
regenerate

저장된 워크플로우 데이터를 사용하여 파라미터 오버라이드 (parameter overrides)와 함께 에셋을 재생성합니다. 세션 격리 (Session isolation):
list_assets

깨끗한 AI 에이전트 컨텍스트 (AI agent context)를 위해 세션별로 필터링할 수 있습니다.

서버가 시작되지 않는 경우:

ComfyUI가 8188 포트 (기본값)에서 실행 중인지 확인하세요.
Python 3.8 이상이 설치되어 있는지 확인하세요 (
python --version
).
모든 종속성 (dependencies)이 설치되었는지 확인하세요:
pip install -r requirements.txt
서버 로그에서 구체적인 에러 메시지를 확인하세요.

클라이언트가 연결할 수 없는 경우:

콘솔에 "Server running at http://127.0.0.1:9000/mcp"가 표시되는지 확인하세요.
서버에 직접 테스트하세요:
curl http://127.0.0.1:9000/mcp
(MCP 응답이 반환되어야 합니다) - .mcp.json 파일이 프로젝트 루트(또는 클라이언트의 올바른 위치)에 있는지 확인하세요.
"type": "streamable-http"와
"type": "http"를 모두 시도해 보세요 - 둘 다 지원됩니다.
Cursor 관련 문제는 docs/MCP_CONFIG_README.md를 참조하세요.

도구가 나타나지 않는 경우:

workflows/ 디렉토리에 PARAM_* 플레이스홀더 (placeholders)가 포함된 JSON 파일이 있는지 확인하세요.
서버 로그에서 워크플로우 파싱 (parsing) 에러를 확인하세요.
(커스텀 워크플로우를 사용하는 경우) ComfyUI에 필요한 커스텀 노드 (custom nodes)가 설치되어 있는지 확인하세요.
새로운 워크플로우를 추가한 후 MCP 서버를 재시작하세요.

에셋을 찾을 수 없는 에러 (Asset not found errors):

에셋은 기본적으로 24시간 후에 만료됩니다 (COMFY_MCP_ASSET_TTL_HOURS를 통해 설정 가능)

) - 서버 재시작 시 에셋이 손실됩니다 (설계상 휘발성)

regenerate를 사용하기 전에 get_asset_metadata를 사용하여 에셋이 존재하는지 확인하십시오.
에셋이 성공적으로 등록되었는지 확인하려면 서버 로그를 점검하십시오.

휘발성 에셋 레지스트리 (Ephemeral asset registry):
asset_id 참조는 MCP 서버가 실행 중인 동안(및 TTL 만료 전까지)에만 유효합니다. 재시작 후에는 이전에 발급된 asset_id를 해결(resolve)할 수 없으며, 해당 에셋들에 대한 regenerate는 실패하게 됩니다.

이슈(Issues) 및 풀 리퀘스트(Pull requests)를 환영합니다! 개발 가이드라인은 CONTRIBUTING.md를 참조하세요.

@venetanji - streamable-http 기반 및 PARAM_* 시스템

Apache License 2.0

comfyui-mcp-server

요약

핵심 포인트

댓글