# 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](#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).

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

Register it with Claude Code:

```bash
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:

```bash
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.