capcut-mcp

An MCP server that reads — and builds — CapCut projects on your own machine.

Point Claude at it and ask in plain language: what's in my CapCut projects, is any media missing, make me a 15 second vertical edit of this video cut on the beat. It works on the local draft library CapCut already keeps on disk.

What it does

Times are in seconds throughout. CapCut stores microseconds internally; the conversion happens in one place so nothing downstream has to think about it.

Related MCP server: capcut-mcp

Install

Requires Node 18+, CapCut installed, and ffmpeg/ffprobe on PATH (used to measure media and to decode audio for beat detection).

git clone https://github.com/<you>/capcut-mcp
cd capcut-mcp
npm install

Register it with Claude Code:

claude mcp add capcut --scope user -- node /absolute/path/to/capcut-mcp/src/index.js

--scope user makes it available in every session. Check it came up:

claude mcp list        # capcut: ... - ✔ Connected

Any MCP client works; the server speaks stdio and nothing else.

Examples

what CapCut projects do I have?

0625      158.8s   1920x1080   2 tracks
0624 (1)  115.3s   1920x1372   1 track
0720        3.4s   1920x1098   1 track

is any of my footage missing?

0720 -> imsobored.mp4   MISSING

A draft stores absolute paths, so moving or deleting a source leaves the edit pointing at nothing and CapCut says so only when you open the project.

make a 16 second vertical edit of that music video, cut on the beat

project   lil-tecca-beat
duration  15.836s across 11 cuts
bpm       166.7  (cut every 4 beats = 1.44s)
canvas    1080x1920

How beat matching works

Decode to mono PCM with ffmpeg, measure how much energy rises between short windows, and treat peaks in that rise as onsets. Then find the tempo by autocorrelation — which beat spacing do the onsets agree with most — and lay a regular grid at that spacing, slid to whichever phase collects the most onset energy.

The grid matters more than the raw onsets. Onsets are uneven: they fire on a vocal, miss a soft kick, double up on a fill. Cutting straight to them looks jittery. A grid locked to the tempo lands musically.

Cut lengths come from the grid; cut contents are sampled evenly across the source, so a short edit surveys the whole video instead of its opening.

Tempo estimation is octave-ambiguous — a 83 BPM track often reads as 166 BPM. It rarely matters for editing, since both give cuts on real beats, but it is why everyNthBeat is the dial to reach for if cuts feel twice as fast as expected.

How creating works

A segment does not merely point at its clip. It also carries extra_material_refs — seven linked materials (speed, canvas, sound channel mapping, vocal separation, animation, placeholder, colour) that must each exist in the pool with matching ids. Synthesising all of that from nothing is how you get a draft that opens to an error instead of a timeline.

So the server clones one of your existing projects as a structural template and rewrites only what describes the media and the timing. Every undocumented field is carried across verbatim from a draft CapCut itself wrote. Each segment gets its own copies of the seven linked materials, so two clips never share a speed object and move together when one is changed.

This is also why you need at least one real project before creating anything — there has to be something to copy the shape from.

Vertical crops

canvas takes a preset (tiktok, reels, shorts, square, youtube) or {width, height}. Clips are scaled to cover the frame rather than fit inside it — left alone, 16:9 footage in a 9:16 canvas sits as a small strip between black bars. 1920x1080 into 1080x1920 lands at scale ≈3.16, keeping the middle third of the width.

The crop is centre-locked. If your subject sits off to one side, that shot loses them; clip.transform in the draft is the lever, and it is not exposed yet.

Safety

• Only ever creates new project folders. Nothing modifies an existing project. Tests assert the template project is byte-identical afterwards.

• Refuses to overwrite. A name that already exists is an error, not a merge.

• Refuses while CapCut is running, because the app holds its open draft in memory and writes it back on exit, which would silently discard new work.

• Project names are validated before touching disk — anything containing /, \ or .. is rejected, so a bad argument cannot read outside the draft root.

• Trims that would leave nothing are rejected with the clip's real length.

Where the drafts live

%LOCALAPPDATA%\CapCut\User Data\Projects\com.lveditor.draft\<project>\
  draft_content.json    the timeline: tracks -> segments -> material ids
  draft_meta_info.json  display name and imported media paths
  draft_cover.jpg       thumbnail

Override with CAPCUT_DRAFT_ROOT if CapCut lives somewhere else. Only Windows paths are wired up by default; macOS keeps drafts under ~/Movies/CapCut/User Data/Projects/com.lveditor.draft, which should work by setting that variable, though it is untested.

Known limits

• Never verified against CapCut itself. The structure is checked thoroughly — every material reference resolves, ids are unique across segments, timings are contiguous, the timeline duration equals the sum of its segments — but "well-formed" and "the app accepts it" are different claims and only the first is tested.

• One video track. No audio tracks, text, transitions, effects or keyframes.

• No transitions between cuts, so a beat edit is hard cuts only.

• Centre crop only.

• Reads and writes video materials; other material types are passed through from the template untouched.

Licence

MIT.