capcut-mcp

An MCP server that lets an LLM agent read and edit local CapCut desktop projects directly — cutting, timing, transforms, keyframed motion, text, transitions, filters, stickers, audio — with an ffmpeg-based preview so the agent can see the result of an edit before committing it.

Requirements

• Windows only. CapCut's desktop draft store, process detection and this tool's discovery logic (registry, tasklist) are Windows-specific. There is no macOS/Linux support.

• Python 3.11+

• CapCut desktop, installed and used at least once

• ffmpeg on PATH (winget install ffmpeg or download a build and add it to PATH) — needed for capcut_frame / capcut_preview

Related MCP server: CapCut MCP

Why this exists

CapCut has no public API, but it stores each project as draft_content.json next to the media. On recent CapCut builds (tested on 9.3.x) that file is plain UTF-8 JSON, so the timeline can be read and rewritten directly — capcut_probe confirms this against a real file on your install rather than assuming it from the version number, since this could change in a future CapCut release.

Most CapCut automation projects are write-only draft builders: a handful of add_* tools, no way to read the timeline back, and no way to look at the result. That makes incremental editing impossible (you can only rebuild from scratch) and leaves every edit unverified until a human opens the app. This server adds the two missing halves:

• Read. capcut_timeline returns the whole project as a flat, seconds-based document. Clips carry short ids used to address them in every edit tool.

• See. capcut_frame and capcut_preview compile that same timeline to ffmpeg, so the agent can look at its own work before saving.

Architecture

draft_content.json  <->  Timeline IR  ->  ffmpeg proxy (preview / frame)
   (CapCut's schema)     (this package's)

The IR is the stable contract. Agents never walk CapCut's material graph, where a segment points at a material_id plus a list of extra_material_refs for its speed, canvas, channel mapping and so on. If a future CapCut update changes that schema, the compiler changes and the tool surface does not — and the ffmpeg proxy keeps working regardless.

Session model

Open, edit, look, save — like an editor:

capcut_probe            check the setup
capcut_projects         find the project
capcut_timeline         read it
capcut_split_clip ...   edits accumulate in memory
capcut_frame            look at the result
capcut_save             write to disk, backing up first

Nothing touches disk until capcut_save, so a bad edit costs nothing. capcut_discard drops in-memory edits; capcut_revert rolls back to a backup.

Two safety rules that matter

CapCut must be closed to save. The app holds its own copy of the project in memory and flushes it on close, which silently discards anything written underneath it. capcut_save refuses while CapCut is running; force=True overrides at your own risk.

Every save backs up first. Timestamped copies land in .mcp_backups/ inside the project folder, 40 kept. capcut_revert restores from one.

Tool reference

Project / timeline

Clips

Keyframes (pure geometry, works on any project — see below)

Catalog-bound (only reapplies what you've used before in CapCut — see below)

Native AI tools

Tracks

Preview

Keyframes: fully general, no catalog needed

Keyframes are pure geometry CapCut's schema already describes in full (a property name, timed points, a curve) — not tied to anything CapCut-cloud, so capcut_set_keyframes works on any project regardless of history. KFTypePositionX, KFTypePositionY and KFTypeScaleX are confirmed against real CapCut drafts; KFTypeScaleY, KFTypeRotation and KFTypeAlpha (used by capcut_add_fade) follow the same naming convention but were not individually observed — verify with capcut_frame, and once in CapCut itself, before depending on them in production. capcut_frame interpolates keyframes for the requested instant, so a Ken Burns pan/zoom is visible in the proxy before you ever save.

No volume-keyframe type was found anywhere, so capcut_add_audio_fade approximates a fade with several tiny sub-clips of graduated flat volume instead of guessing a shape that might not exist. Same story for capcut_speed_ramp: no populated smooth speed-curve was found, so it splits the clip into flat-speed pieces instead — no visible seam on screen, but it does show up as separate clips in capcut_timeline.

Catalog-bound tools: reapply, not invent

CapCut resolves every transition, effect, filter, animation, audio effect and sticker against its own cloud catalog by an opaque numeric resource_id — there is no offline API to browse that catalog or mint an id for something never used before. What is available locally is every resource_id CapCut has already cached on your machine, because you (or whoever uses this install) applied it by hand at least once. catalog.py mines that out of every local draft into a searchable name index, and the catalog-bound tools deep-copy the exact material CapCut itself produced for that past use — cache path, sub-parameters and all — substituting only a fresh id.

Consequence: these tools can only reapply what has already been used — never invent something new. capcut_catalog_search shows what's actually available on your machine; capcut_catalog_refresh re-scans after applying something new by hand in CapCut. On a fresh CapCut install with an empty history, the catalog starts empty — use CapCut's own UI to apply a handful of transitions/effects/filters/stickers you like once, and they become reapplicable by the agent from then on.

Native AI tools: what does and doesn't work

CapCut's built-in AI tools split into two very different architectures, and this was verified against real local drafts rather than assumed:

• Noise reduction works (capcut_set_denoise). It references a model file CapCut ships with itself — the same file for every clip, not a per-clip derived output — so there's nothing to precompute; flipping the flag is what CapCut's own "Reduce noise" toggle does. is_denoise: true is CapCut's own default on nearly every clip observed, so an explicit off-to-on toggle in a real project hasn't been directly observed — confirm audibly (or in CapCut) on anything noise-critical.

• Vocal/music separation and background removal (matting) do not. A real example of vocal separation was found in local drafts, and it requires CapCut to have already run its own AI pipeline and written a derived audio file into the project's own Resources/ folder before the setting means anything — editing the JSON flag alone, without that file, leaves a broken reference. The same architecture was confirmed for background removal (matting, always an empty, unprocessed stub in every local example). This package does not fake either of these.

  • Workaround: run vocal separation or background removal with a dedicated tool outside CapCut (e.g. Demucs for stem separation, or any matting model), then bring the result in as a normal file via capcut_add_clip — often better quality and more controllable than driving CapCut's own black-box pipeline anyway.

• AI image/video generation is not reachable at all. CapCut's AI asset generation is a cloud service tied to your CapCut/Jianying account (real aigc_config/prompt/seed/model fields were found in the schema, confirming server-side generation, not a local model this package could drive). This is intentionally not implemented — it would mean reverse-engineering a private, authenticated, undocumented API of a consumer product. Generate assets with a tool you control instead, then import the result the same way as above.

• Caption/text style templates and full downloadable project templates use the same resource_id-catalog architecture as transitions/effects (the schema fields — preset_id, text_preset_resource_id, template_id — are there), but starts empty until you've applied at least one by hand in CapCut, same as any other catalog-bound feature.

Preview fidelity

The ffmpeg proxy honours layout, trims, speed, opacity, volume, crop, background fill, text position/z-order and keyframed motion. It does not render CapCut's own transitions, filters, effects, stickers or audio effects at all — a cached resource's file path was confirmed to sometimes be a directory of resource-type-specific mixed content (JSON algorithm configs, sub-hashed folders) rather than one directly renderable file, so this was not something to guess at wiring up.

In practice: capcut_frame/capcut_preview are fully reliable for verifying layout, crop, keyframes and background before saving, but currently blind to whether a catalog-reapplied effect/filter/transition/sticker looks right — that still needs opening the saved project in CapCut once.

Known limits

• Reading drafts depends on them staying plaintext JSON on your CapCut version. capcut_probe checks this directly rather than trusting the version number.

• Shaped masks (circle, custom path, feathered edge) are not supported — no write schema was found; the closest boolean-looking field is just a generic toggle, not a real mask reference. capcut_set_crop gives rectangular crops only.

• No dedicated LUT bucket exists in the schema; color grading beyond a catalog capcut_add_filter (true LUT files, curves/wheels/HSL) is read-only via capcut_timeline.

• Export is not automated. Render the ffmpeg proxy here, or open CapCut and export normally.

Install

uv venv --python 3.13
uv pip install -e .

Register with Claude Code:

claude mcp add capcut -s user -- "<path-to-repo>/.venv/Scripts/capcut-mcp.exe"

(On Windows/PowerShell, run this from a shell where -- isn't swallowed — Git Bash works; if using PowerShell directly, use claude --% escaping or call the venv's capcut-mcp.exe path directly as shown.)

If the draft store isn't found automatically (capcut_probe reports it missing), set CAPCUT_MCP_DRAFT_ROOT to the folder containing root_meta_info.json (normally under %LOCALAPPDATA%\CapCut\User Data\Projects\com.lveditor.draft, but this can be on a different drive if CapCut was reinstalled after a drive change).

Verify your install

.venv/Scripts/python.exe scripts/verify_setup.py    # install/paths/ffmpeg — safe on an empty install
.venv/Scripts/python.exe scripts/verify_tools.py    # prints all 35 tools — safe on an empty install
.venv/Scripts/python.exe scripts/verify_render.py   # needs at least one real CapCut project with a clip

verify_render.py works on a scratch copy of your first project; it never modifies your real projects.

Contributing

Issues and PRs welcome. If you're adding a tool that touches a new part of CapCut's schema, please base it on a real example found in an actual local draft (as every tool in this repo was) rather than a guessed shape — CapCut's draft format is undocumented, and a plausible-looking but wrong field can silently corrupt a project.

License

MIT — see LICENSE.