🔌 MCP 서버

Claude Code 연동 가이드

Model Context Protocol을 통해 Claude Code에서 AutoFlowCut을 직접 제어하세요

🤖 MCP란?

Model Context Protocol(MCP)을 사용하면 Claude Code에서 AutoFlowCut을 터미널로 직접 제어할 수 있습니다. CSV 씬 로드, 프롬프트 수정, 배치 이미지 생성, CapCut 내보내기까지 — 모두 자연어 명령으로 가능합니다.

MCP 서버는 stdio를 통해 Claude Code와 통신하고, 로컬 HTTP API(포트 3210)를 통해 실행 중인 AutoFlowCut 앱에 연결됩니다.

🏗️ 아키텍처 

Claude Code ←→ MCP Server (stdio) ←→ Electron App (HTTP :3210)
                  ↕                            ↕
           CSV / project.json          React Renderer (IPC)
           .audio_review.json          State 직접 변경
1. CSV 직접 관리 — 디스크의 CSV와 project.json 파일 읽기/쓰기
2. HTTP 앱 제어 — localhost API를 통해 실행 중인 앱 상태 직접 조작

🧰 도구 카테고리

📊 CSV 관리

CSV 파일에서 씬을 로드, 목록 조회, 검색, 수정, 저장합니다. 프롬프트 일괄 업데이트 및 씬 필드 관리를 지원합니다.

load_csv list_scenes update_prompt save_csv

🖼️ 레퍼런스 도구

project.json의 캐릭터 및 씬 레퍼런스를 관리합니다. 목록 조회, 상세 확인, 프롬프트 수정을 지원합니다.

list_references get_reference update_reference_prompt

🎬 앱 제어

HTTP를 통해 실행 중인 앱을 제어합니다 — app_* 도구 19개와 내보내기 도구 2개. 프로젝트 관리, 이미지 생성, 배치 실행, 상태 모니터링, 내보내기를 수행합니다. 아래는 일부만 표시한 것입니다.

app_open_project app_generate_scene app_start_scene_batch app_wait_batch app_batch_status export_capcut export_premiere app_* 14개 더

🚦 워크플로우 진행 상태

파이프라인의 웨이브 진행 상태를 조회하고, QA 검수 상황을 앱 배너에 알립니다. 진행 상태는 읽기 전용이며, 기록은 스킬이 직접 수행합니다.

get_progress app_notify_qa

🧩 스킬 관리

Claude Code용 AutoFlowCut 스킬을 설치·조회·제거합니다. 설치 시 템플릿 변수가 치환됩니다.

list_skills install_skill uninstall_skill

🎧 오디오 검수 & 스타일

오디오 패키지의 부적합한 나레이션·효과음 파일에 교체 마크를 추가/해제하고, 내장 스타일 프리셋을 조회합니다.

list_audio_reviews update_audio_review list_styles

📖 주요 도구 레퍼런스

도구 설명
load_csv CSV 파일과 이미지 디렉토리 로드
list_scenes 범위 지정 가능한 씬 목록 조회
update_prompt 개별 씬의 영문 프롬프트 수정
batch_update_prompts 여러 씬의 프롬프트 일괄 수정
app_start_scene_batch 대기 중인 씬의 배치 이미지 생성 시작
app_wait_batch 배치 생성 완료까지 대기 (long-poll)
export_capcut CapCut 프로젝트로 내보내기
export_premiere Premiere Pro 프로젝트(.prproj)로 내보내기
get_schema CSV/SRT/오디오 스키마 문서 조회
list_styles 스타일 프리셋을 카테고리별로 조회
get_progress 파이프라인 웨이브 진행 상태 조회 (읽기 전용)

🚦 워크플로우 진행 상태

9개의 웨이브(W1~W9) 파이프라인은 story-engine Claude Code 스킬의 것입니다 — 앱에 내장된 스토리 모드가 아닙니다. 내장 스토리 모드는 대본 → 씬 분리 → 오디오 → 프롬프트로 진행하며 웨이브가 없습니다. 스킬의 오케스트레이터가 프로젝트의 _story_source/ 폴더에 워크플로우 상태를 직접 기록합니다. 워크플로우 상태를 기록하는 MCP 도구는 없습니다 — MCP 서버는 get_progress로 읽기만 합니다.

워크플로우 상태 파일

파일 역할 기록 주체
STATE.md 메인 상태 — 현재 웨이브, 완료 단계, 결정사항 story-engine 스킬
W{N}_SUMMARY.md 웨이브별 결과, 리뷰 라운드, 이슈 story-engine 스킬
W_progress.json 사이드 로그 — 앱·외부 도구용 waves.W1~waves.W9 상태 story-engine 스킬 (get_progress로 조회)

사용법

# W_progress.json에서 웨이브 진행 상태 조회
get_progress()

# QA 검수 진행 상황을 앱 상단 배너에 알림
app_notify_qa(kind="scene", state="progress", current=12, total=40, round=1, issues=3)

🌐 HTTP API 엔드포인트

AutoFlowCut 설정에서 MCP HTTP 서버를 활성화하면 127.0.0.1:3210에서 사용할 수 있습니다.

메서드 경로 설명
GET /api/status 서버 상태 확인
GET /api/references 레퍼런스 목록 (base64 이미지 제외)
GET /api/scenes 씬 목록 (이미지 데이터 제외)
GET /api/batch-status 배치 생성 진행 상태
POST /api/generate-reference 레퍼런스 이미지 생성 트리거
POST /api/generate-scene 개별 씬 이미지 생성 트리거
POST /api/start-batch 전체 배치 생성 시작
POST /api/update 범용 상태 업데이트 (IPC 중계)

📚 관련 가이드

파일 가져오기 가이드 CapCut 내보내기 가이드 스킬 가이드 오디오 패키지 가이드 스토리 모드 가이드