🔌 MCP Server

Claude Code Integration Guide

Control AutoFlowCut directly from Claude Code via Model Context Protocol

🤖 What is MCP?

Model Context Protocol (MCP) lets Claude Code control AutoFlowCut directly from your terminal. Load CSV scenes, update prompts, trigger batch image generation, and export to CapCut — all through natural language commands.

The MCP server communicates via stdio with Claude Code, and connects to the running AutoFlowCut app through a local HTTP API on port 3210.

🏗️ Architecture

Claude Code ←→ MCP Server (stdio) ←→ Electron App (HTTP :3210)
                  ↕                            ↕
           CSV / project.json          React Renderer (IPC)
           .audio_review.json          State Direct Mutation

1. CSV Direct — Read/write CSV and project.json files on disk

2. HTTP App Control — Manipulate running app state via localhost API

📦 Installation

Method A: Global (Recommended)

Available across all your projects. Stored in ~/.claude.json.

Terminal

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

Method B: Project Local (.mcp.json)

Per-project setup. Create .mcp.json in your project root.

.mcp.json

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

Verify installation:

claude mcp list

🧰 Tool Categories

📊 CSV Management

Load, list, search, update, and save scenes from CSV files. Batch update prompts and manage scene fields.

load_csv list_scenes update_prompt save_csv

🖼️ Reference Tools

Manage character and scene references in project.json. List, inspect, and update reference prompts.

list_references get_reference update_reference_prompt

🎬 App Control

Control the running app via HTTP. Generate images, start batch processing, monitor status, and export to CapCut.

app_start_scene_batch app_wait_batch export_capcut

🔧 Workflow Gates

Track pipeline progress through review steps. Mark steps as pass/fail and check workflow status.

mark_step_done get_progress

📖 Key Tools Reference

Tool	Description
load_csv	Load CSV file and optional image directory
list_scenes	List all scenes with optional range filtering
update_prompt	Update a single scene's English prompt
batch_update_prompts	Bulk update multiple scene prompts at once
app_start_scene_batch	Start batch image generation for pending scenes
app_wait_batch	Wait for batch generation to complete (long-poll)
export_capcut	Export project to CapCut format
get_schema	Get CSV/SRT/Audio schema documentation
list_styles	List all 87 style presets by category

🚦 Workflow Gate System

The pipeline follows sequential steps (R1 through R12). Each step must pass review before the next step unlocks. Progress is tracked in R_progress.json.

Gate Prerequisites

Step	Phase	Prerequisite
R1-R3	Script & CSV Setup	None
R4-R6	References & Prompts	R3 pass
R7-R9	Image Generation & Review	R6 pass
R10-R12	Audio, Export & Final	R9 pass

Usage

# Mark a step as passed
mark_step_done(step="R10-3_scenes_review", result="pass", reviewer="subagent")

# Check overall progress
get_progress()

🌐 HTTP API Endpoints

When the MCP HTTP server is enabled in AutoFlowCut settings, these endpoints are available at 127.0.0.1:3210.

Method	Path	Description
GET	/api/status	Server health check
GET	/api/references	List references (without base64 images)
GET	/api/scenes	List scenes (without image data)
GET	/api/batch-status	Batch generation progress
POST	/api/generate-reference	Trigger reference image generation
POST	/api/generate-scene	Trigger individual scene generation
POST	/api/start-batch	Start batch generation for all pending scenes
POST	/api/update	Generic state update (IPC relay)

📚 Related Guides

File Import Guide Export to CapCut Guide Skills Guide Audio Package Guide