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
🧰 Tool Categories
📊 CSV Management
Load, list, search, update, and save scenes from CSV files. Batch update prompts and manage scene fields.
🖼️ Reference Tools
Manage character and scene references in project.json. List, inspect, and update reference prompts.
🎬 App Control
Control the running app via HTTP. Generate images, start batch processing, monitor status, and export to CapCut.
🔧 Workflow Gates
Track pipeline progress through review steps. Mark steps as pass/fail and check workflow status.
📖 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) |