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.

[!WARNING] This is extremely experimental and is not guaranteed to work.

CapCut's draft format is undocumented, changes with the app, and differs between platforms and versions. Everything here was worked out by reading drafts CapCut wrote on one Windows install. A project this generates may fail to open, may open with pieces missing, or may look fine and behave oddly.

Open anything it creates in CapCut and check it before you build on it. Nothing here has been tested against CapCut itself — only against the file format. Treat generated projects as drafts to inspect, not as finished work.

It will not touch projects you already have (see Safety), so the realistic worst case is a project that does not open. But back up work you care about anyway.

---

What it does

Tool	Purpose
capcut_list_projects	Every project, newest first — duration, resolution, fps, track count
capcut_read_project	One timeline: each track, each segment, its start, length, speed and material
capcut_project_media	Source files a project needs, their size, and whether they still exist
capcut_create_project	Build a new project from clips laid end to end, each optionally trimmed
capcut_detect_beats	Tempo and beat times of any file with audio
capcut_create_beat_edit	Build a new project whose cuts land on the beat

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

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.