capcut-mcp

An MCP server that assembles CapCut International projects and generates the assets CapCut cannot make itself, so an editor opens a timeline that is mostly done instead of an empty one.

Independent and unofficial. Not affiliated with ByteDance or CapCut. It works by reading and writing CapCut's local project files, a private and undocumented format. Use on projects you can afford to have backed up.

Status: early. Verified by hand on CapCut 9.1.0 (Windows). Every write tool is gated behind check_compatibility, and restyle_captions has a dryRun mode.

---

What it is, and what it is not

Is: a draft compiler. Cuts, captions, music, titles and code-driven overlays assembled into a real CapCut project.

Is not: a renderer, and not a replacement for the editor. CapCut's AI features — auto-captions, auto-reframe, cloud effects — run on ByteDance servers. A project file can only reference resources that already exist in their catalogue. This tool cannot invoke them, and will not pretend otherwise.

The split it is built around: the machine does assembly, the human does taste. Uniform caption styling across a whole video is assembly. Masking, keyframe easing and colour grading are taste.

---

Requirements

• Node.js ≥ 20
• CapCut International (app_source: "cc"). JianYing is not supported — from 6.0 it encrypts the project on every save, which makes round-trip editing impossible.
• ffmpeg / ffprobe — optional for reading, required for overlay rendering
• CapCut must be closed when writing. The editor holds the project in memory and overwrites the file on close.

---

Setup

1. Install and build

git clone https://github.com/yabdulaziz2009-dev/capcut-mcp.git
cd capcut-mcp
npm install
npm run build          # compiles src/ -> dist/

Optional, and only if you want render_overlay / compose_overlay — it pulls a headless browser (~hundreds of MB):

npm install --prefix remotion

2. Register the server with your MCP client

The server speaks stdio and takes no arguments beyond its own path. Use the absolute path to dist/index.js.

Claude Code — one command:

claude mcp add capcut -- node /absolute/path/to/capcut-mcp/dist/index.js

Claude Desktop — claude_desktop_config.json (%APPDATA%\Claude\ on Windows, ~/Library/Application Support/Claude/ on macOS):

{
  "mcpServers": {
    "capcut": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/absolute/path/to/capcut-mcp/dist/index.js"]
    }
  }
}

On Windows use forward slashes in the JSON, or escape the backslashes (C:\\Users\\…).

Restart the client, then ask it to list your CapCut projects. If list_projects returns your drafts, the server is wired up.

3. Where projects are read from

The local draft store is found automatically:

OS	Path
Windows	%LOCALAPPDATA%\CapCut\User Data\Projects\com.lveditor.draft
macOS	~/Movies/CapCut/User Data/Projects/com.lveditor.draft

Every tool also accepts an explicit project path — either the project folder or its draft_content.json.

Verify

npm test           # 32 unit tests, no CapCut install needed
npm run typecheck

Troubleshooting

Symptom	Cause
Tools missing after restart	Path in the config is relative, or npm run build was never run
refuse: editor is running	CapCut is open — close it, it rewrites the draft on exit
refuse: JianYing draft	Encrypted format, not supported (see above)
render_overlay fails	ffmpeg not on PATH, or npm install --prefix remotion was skipped
Changes vanish	The project was open in CapCut during the write

---

Tools

Tool	What it does	Writes?
list_projects	CapCut projects in the local draft store	no
inspect_project	Duration, tracks, subtitles as readable text, populated material buckets	no
check_compatibility	ok / warn / refuse verdict before any write	no
restyle_captions	One style across every caption at once, plus an entrance animation	yes
import_subtitles	An SRT file (or raw SRT text) as a styled caption track, with keyword highlighting	yes
render_overlay	Animated motion graphics with a real alpha channel (ProRes 4444)	no
add_overlay	Place a rendered clip on its own track	yes
compose_overlay	Render and place in one call	yes

restyle_captions

The most repetitive job in short-form editing: the same outline, shadow and plate on every caption, set by hand one segment at a time.

Presets: bold-outline (white on heavy black stroke — the shorts default), boxed (rounded dark plate), accent (brand colour with dark outline). A preset can be nudged field by field rather than replaced.

Supported: size, colour, weight, opacity, outline, shadow (colour, angle, distance, blur), background plate, entrance/exit animation from 76 upstream slugs.

Not supported — and it says so instead of pretending: font family and on-screen position. Neither is reachable through capcut-cli; see GATE0-FINDINGS.md §6.

Re-running is safe: captions that already carry an animation keep it and are reported, because upstream can add an animation but not replace one.

render_overlay — the differentiator

CapCut cannot author code-driven motion graphics; editors leave for Remotion and come back with a transparent clip. This closes that loop.

Kinds: lower-third (name bar), title-card (centred statement), callout (pill badge). Text, colours, size, duration and exit timing are parameters — no code is generated per overlay.

Output is ProRes 4444, yuva444p10le — verified to carry a genuine alpha channel (93–96% of pixels fully transparent on the shipped kinds), not a black background.

Confirmed end-to-end on CapCut 9.1 / Windows: the rendered overlay was placed on its own track and the footage showed through its transparent areas in the editor.

npm install --prefix remotion     # one-time, pulls a browser (~hundreds of MB)

Requires ffmpeg. A 2.5-second 1080×1920 overlay renders in ~17 s.

The Remotion project lives in remotion/ as a sibling package, not a dependency of the server, so installing capcut-mcp does not drag a browser along for the tools that never need one.

Always run check_compatibility first. It refuses on JianYing drafts, a running editor, an upstream write-guard block, or pre-existing integrity errors — and warns about untested CapCut versions, diverged storage mirrors and missing binaries.

Version support

Verified by hand on CapCut 9.1.0 (Windows): an externally written text segment survived being opened in the editor. Details and the defects found along the way are in GATE0-FINDINGS.md.

CapCut 9.x has no upstream test fixture, so check_compatibility reports it as untested even though it works here. That is deliberate: the format is private and can change without warning, and an honest warning beats a silent corruption.

Credit

Draft reading and writing is done by capcut-cli (MIT), which handles the transactional multi-file write CapCut 9.x needs — the modern layout keeps a template-2.tmp mirror beside draft_content.json, and both must stay in sync. This project adds the MCP layer, workflow-level composites, and the Remotion overlay bridge.

Licence

MIT.