🔌 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를 통해 실행 중인 앱 상태 직접 조작

📦 설치

방법 A: 글로벌 설정 (권장)

모든 프로젝트에서 사용 가능합니다. ~/.claude.json에 저장됩니다.

터미널

cd /path/to/Flow2CapCut/mcp-server
npm install
claude mcp add --scope user --transport stdio flow2capcut -- node $(pwd)/index.js

방법 B: 프로젝트 로컬 (.mcp.json)

특정 프로젝트에서만 사용합니다. 프로젝트 루트에 .mcp.json을 생성하세요.

.mcp.json

{
  "mcpServers": {
    "flow2capcut": {
      "command": "node",
      "args": ["/path/to/Flow2CapCut/mcp-server/index.js"]
    }
  }
}

설치 확인:

claude mcp list

🧰 도구 카테고리

📊 CSV 관리

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

load_csv list_scenes update_prompt save_csv

🖼️ 레퍼런스 도구

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

list_references get_reference update_reference_prompt

🎬 앱 제어

HTTP를 통해 실행 중인 앱을 제어합니다. 이미지 생성, 배치 처리, 상태 모니터링, CapCut 내보내기를 수행합니다.

app_start_scene_batch app_wait_batch export_capcut

🔧 워크플로우 게이트

리뷰 단계를 통해 파이프라인 진행 상태를 추적합니다. 단계별 통과/실패 판정 및 전체 진행률을 확인합니다.

mark_step_done get_progress

📖 주요 도구 레퍼런스

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

🚦 워크플로우 게이트 시스템

파이프라인은 순차적 단계(R1~R12)를 따릅니다. 각 단계는 리뷰를 통과해야 다음 단계가 열립니다. 진행 상태는 R_progress.json에 기록됩니다.

게이트 선행 조건

단계	페이즈	선행 조건
R1-R3	스크립트 & CSV 설정	없음
R4-R6	레퍼런스 & 프롬프트	R3 통과
R7-R9	이미지 생성 & 리뷰	R6 통과
R10-R12	오디오, 내보내기 & 최종	R9 통과

사용법

# 단계를 통과로 표시
mark_step_done(step="R10-3_scenes_review", result="pass", reviewer="subagent")

# 전체 진행률 확인
get_progress()

🌐 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 중계)