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 — 19 app_* tools plus two exporters. Manage projects, generate images, run batches, monitor status, and export. Only a few are shown here.
🚦 Workflow Progress
Read the pipeline's wave progress and report QA review status to the app's banner. Progress is read-only — the skill writes it.
🧩 Skill Management
Install, list, and remove AutoFlowCut skills for Claude Code. Template variables are substituted on install.
🎧 Audio Review & Styles
Flag and unflag unsuitable narration/SFX files in an audio package, and browse the built-in style presets.
📖 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 |
| export_premiere | Export project to Premiere Pro (.prproj) format |
| get_schema | Get CSV/SRT/Audio schema documentation |
| list_styles | List the style presets, grouped by category |
| get_progress | Read the pipeline's wave progress (read-only) |
🚦 Workflow Progress
The nine-wave pipeline (W1–W9) belongs to the story-engine Claude Code skill — not to the app's built-in Story mode, which runs script → scene split → audio → prompts and has no waves. The skill's orchestrator writes workflow state directly to files in the project's _story_source/ folder. No MCP tool writes workflow state — the MCP server only reads it, via get_progress.
Workflow State Files
| File | Role | Written by |
|---|---|---|
| STATE.md | Main state — current wave, completed steps, decisions | story-engine skill |
| W{N}_SUMMARY.md | Per-wave results, review rounds, issues | story-engine skill |
| W_progress.json | Side log — waves.W1…waves.W9 status for the app and external tools |
story-engine skill (read via get_progress) |
Usage
# Read wave progress from W_progress.json get_progress() # Report QA review progress to the app's status banner app_notify_qa(kind="scene", state="progress", current=12, total=40, round=1, issues=3)
🌐 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) |