capcut-mcp
This server lets Claude read, edit, validate, and save CapCut desktop draft projects through MCP tools, enabling full video-editing workflows (clips, text, audio, effects, captions, keyframes) with safety backups.
Draft management: list drafts, clone drafts (optionally empty), read full timeline, save/discard/undo session edits
Media editing: add video, image, audio, text, stickers; move, trim, split, delete segments (with ripple options)
Track control: add tracks, mute/unmute tracks, set track/layer ordering
Properties & animation: set position, scale, rotation, opacity, volume, speed, visibility; add/remove keyframes for real property animation over time
Effects: apply bundled real CapCut filters, transitions, masks (with intensity, duration, shape params); add audio fades
Captions & transcription: transcribe audio (Deepgram or local Whisper), review transcript confidence, generate styled auto-captions, clear caption tracks
Inspection & verification: list filters/transitions/masks/caption styles, validate drafts for overlaps/duplicate ids/missing media
Advanced: raw JSON patch escape hatch for unsupported edits; atomic saves with backups and guardrails against open-CapCut/clobbering
Provides tools for reading and editing CapCut desktop draft projects, including managing clips, text, audio, images, filters, transitions, masks, keyframes, and more in CapCut draft files.
Uses ffmpeg/ffprobe to read media duration and resolution for CapCut draft editing.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@capcut-mcp Apply a 'Blur' filter to the first clip in draft 'Vlog'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
capcut-mcp (fork)
An MCP server that lets Claude read and edit CapCut desktop draft projects — add/move/trim/split clips, text, audio, images; filters, transitions, masks, keyframe animation, audio fades, stickers; set transforms; validate; save; undo. It works by cloning real segment/material templates out of an existing draft (the only reliable way to produce valid CapCut JSON) plus a bundled catalog of real CapCut filter/transition/mask resource IDs (see Bundled effect catalog), and it saves atomically with a backup and a validation pass.
This is a fork of JmsLdrn/capcut-mcp by James Aldrin Boncales, maintained here with security fixes and capability additions (see commit history). Still free & open source (MIT) — original copyright retained in LICENSE.
Not affiliated with CapCut or ByteDance. CapCut's draft format is proprietary and undocumented; this tool reads/writes it defensively (clone-from-template, backups, validation), but a CapCut update can shift the schema. Keep the backups it makes.
Requirements
Node 18+
ffmpeg/ffprobe on PATH (used to read media duration/resolution)
CapCut desktop (Windows layout assumed; macOS path is auto-detected too)
Related MCP server: Arkeonix CapCut MCP
Configure (env, optional)
CAPCUT_DRAFTS_DIR— your CapCut Drafts folder. Auto-detects the standard%LOCALAPPDATA%\CapCut\...(Windows) /~/Movies/CapCut/...(macOS) locations; set this if your drafts live elsewhere (e.g. a different drive).CAPCUT_TEMPLATE_DRAFT— name of a draft that contains video and text layers, used to harvest templates when the draft you're editing lacks one. Default0723is the author's own draft and won't exist on your machine — set this to one of your drafts that has a text layer, orcapcut_add_text/capcut_add_captionswon't work. (Everything else works without it.)DEEPGRAM_API_KEY— needed forcapcut_transcribe's default provider. See Auto-captions.CAPCUT_WHISPER_PYTHON— path to the local ASR venv'spython.exe, if you moved it from the defaultvendor/whisper-env/.CAPCUT_PROFILES_DIR— wherecapcut_add_captions'cliente:"name"looks for{name}.mdclient profiles. Defaults to../perfis-criativorelative to this repo.
Install
git clone https://github.com/JmsLdrn/capcut-mcp
cd capcut-mcp
npm installThen register it in Claude Code — use the absolute path to src/server.js on your machine:
claude mcp add capcut --scope user -- node "/ABSOLUTE/PATH/TO/capcut-mcp/src/server.js"…or add a project-scoped .mcp.json at your repo root (copy mcp.json.example and edit the paths):
{
"mcpServers": {
"capcut": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/capcut-mcp/src/server.js"],
"env": { "CAPCUT_DRAFTS_DIR": "", "CAPCUT_TEMPLATE_DRAFT": "" }
}
}
}Leave the env values blank to auto-detect, or fill them in (see Configure above). Restart Claude Code; the tools then appear as mcp__capcut__*.
Workflow (important)
Close CapCut on the draft you want to edit. CapCut autosaves on a timer; writing while it's open gets clobbered.
capcut_saverefuses if CapCut is running or the draft's.lockedfile is present (override withforce: trueonly if you know it's safe).Edits are a session:
capcut_add_*/capcut_move_*etc. accumulate in memory. Nothing hits disk untilcapcut_save.capcut_savewritesdraft_content.json(+ meta) atomically after making a.mcpbakbackup, and runscapcut_validate.Reopen the draft in CapCut.
All times at the tool boundary are in seconds (converted to CapCut's microseconds internally).
Tools
Tool | Purpose |
| list drafts + duration + lock status |
| full read: canvas, fps, tracks, every segment (reflects pending session edits) |
| copy a draft (optionally emptied) for a fresh build |
| place media on a track. Omit |
| text overlay (needs a text template draft). Omit |
| new video/audio/text/sticker track |
| mute/unmute an entire track — a track cloned from a muted template starts muted with no visible sign of it besides this field |
| change start time / track |
| change start / duration / source in-point. |
| split at a time |
| remove. |
| scale / position / rotation / opacity / volume / speed / visibility (static value for the whole segment) |
| search the bundled real-CapCut catalog by name |
| attach a real filter (from the catalog) to a segment, with optional intensity |
| attach a real transition on a segment, applied to whatever follows it on the same track |
| attach a mask shape (circle/rectangle/heart/star/linear/mirror) with position/size/feather/rounding |
| real per-property animation over time (position/scale/rotation/alpha/saturation/contrast/brightness/volume) — not just a static value. |
| fade-in/fade-out duration on an audio segment |
| place a sticker by CapCut |
| step back up to 20 in-session edits (does not touch anything already saved) |
| extract audio + transcribe with word-level timestamps (Deepgram, default; or |
| list transcript words below a confidence threshold, for a quick human check |
| generate real auto-captions from a transcript, applying a style preset from |
| remove all segments from a caption track, to switch styles or start over |
| search the 10 bundled business-niche caption presets |
| advanced deep-merge escape hatch for anything not covered above |
| overlaps, duplicate ids, missing media — now enforced by |
| persist / drop the session |
capcut_save now refuses to write (unless force:true) if capcut_validate reports issues, or if the draft changed on disk since this session loaded it (e.g. you edited it in CapCut in the meantime).
Companion skill
A Claude skill ships in skills/capcut-reels/. It teaches Claude the full production pipeline these tools were built for — record → captions (WhisperFlow) → motion graphics (HyperFrames) → probe/render (ffprobe/ffmpeg) → assemble & caption the CapCut draft via this MCP. Copy the capcut-reels folder into your Claude skills directory to install it.
Bundled effect catalog
Filters, transitions, and masks in real CapCut are not freely inventable — CapCut resolves them by a matched (resource_id, effect_id) pair from its own asset catalog, not from arbitrary strings. Rather than only being able to reuse whatever effect happened to already be in one of your drafts, this fork bundles a real catalog as data-only JSON (src/metadata/*.json), extracted from Python source in sun-guannan/VectCutAPI (which vendors GuanYixuan/pyJianYingDraft) — both Apache License 2.0. Full provenance and license text pointer in src/metadata/NOTICE.md.
474 filters (
capcut_list_filters) — shared JianYing/CapCut catalog; basic filters are believed cross-compatible but this isn't independently confirmed (see NOTICE.md)116 transitions (
capcut_list_transitions) — from CapCut's own dedicated catalog, high confidence9 masks: Circle, Rectangle, Heart, Stars, Text, Split, Filmstrip, Brush, Pen (
capcut_list_masks) — CapCut-specific, high confidence
Not yet ported: the video/character scene-effects catalog (1,000+ entries with per-effect adjustable parameters) and canned intro/outro/loop animations — both exist in the same upstream metadata and could be added the same way, just not done yet. Use capcut_raw_patch for those in the meantime.
Stickers are different: CapCut's sticker library is too large and changes too often to bundle, so capcut_add_sticker takes a raw resource_id you obtain by inspecting a draft where that sticker was placed once (by you or the user, in the real app).
Masks key confirmed against a real draft: research disagreed on whether masks live under materials.masks or materials.common_mask — inspecting an actual CapCut 9.4.0 draft settled it: it's common_mask (masks doesn't exist in a real draft's materials at all). addMask uses common_mask.
Auto-captions
capcut_transcribe → (optional) capcut_review_transcript → capcut_add_captions → capcut_validate → capcut_save. Needs a text template draft, same requirement as capcut_add_text (see Configure above).
Transcription provider:
deepgram(default) — needs a Deepgram account andDEEPGRAM_API_KEYset as an environment variable. ~US$0.004-0.005/min, pt-BR by default (passlanguage:"multi"for heavy pt/en code-switching).local— no account, no cost, nothing leaves your machine. Needs a one-time setup:python -m venv vendor/whisper-env vendor/whisper-env/Scripts/python -m pip install -r vendor/requirements-whisper.txt --extra-index-url https://download.pytorch.org/whl/cu126See the header of
vendor/requirements-whisper.txtfor why the--extra-index-urlmatters (installingfaster-whisper/whisperxany other way can silently downgrade a working CUDA build oftorchto a CPU-only one). No NVIDIA GPU? Drop that flag — it still works, just slower than real-time on a full clip. Override the interpreter path withCAPCUT_WHISPER_PYTHONif you move the venv.
Caption styles: 10 business-niche presets (src/metadata/caption_styles.json) covering color, chunking (max words/chars, target reading speed), entrance animation (via the real addKeyframe(), not a static value), and word-by-word "karaoke" highlighting for the niches that call for it. A numeric token (price, %, count) always gets isolated into its own cue and — for karaoke styles — its own highlighted moment. cliente:"name" (matching a file in perfis-criativo/) auto-resolves an accent-color override from that client's real palette; accentColorOverride sets one explicitly.
Known limitation: font family/weight and pill/outline backgrounds aren't in the confirmed-safe schema yet (see Bundled effect catalog reasoning) — presets differentiate today via color, size, chunking, and animation. capcut_add_captions on a style whose localOnly flag is set (jurídico/financeiro, saúde) is a hint to route through provider:"local" in capcut_transcribe for that content, not an enforced rule.
Guardrails
Won't save while CapCut is open (autosave clobber protection), or if the draft changed on disk since this session loaded it.
Won't save a draft
capcut_validateflags as broken (overlaps, duplicate ids, render_index clashes, out-of-range keyframes, dangling material references) unlessforce:true.capcut_read_timelineshows an explicitwarningwhen CapCut is open on the draft you're editing..mcpbakbackup + atomic temp-then-rename write.New drafts are cloned from a known-good base, never built from an empty object.
capcut_undosteps back through in-session edits (up to 20), independent of the disk.
Limitations (be honest with these)
CapCut's draft format is proprietary and undocumented, and changes between CapCut versions. This server is defensive (clone-from-template, backup, validate) but a CapCut update can still shift the schema — keep the backups.
Filters/transitions/masks are limited to what's in the bundled catalog (see above) — ask for something not in it and
capcut_add_filter/_transition/_maskwill say so rather than silently failing.Video/character scene effects (blur, glitch, etc.) and canned intro/outro animations aren't ported yet — use
capcut_raw_patch.Rich multi-style text (per-word styling, karaoke captions) is still a single uniform style per text block.
capcut_add_textneeds a draft with a text layer to harvest from (CAPCUT_TEMPLATE_DRAFT).No canvas/aspect-ratio retargeting (e.g. 16:9 → 9:16) yet.
Architecture
src/core.js— pure engine (CapCutDraftclass +cloneDraft/listDrafts+ the bundled catalog helpers). Testable without MCP.src/server.js— thin MCP stdio server; declares the tools and calls the core.src/metadata/*.json— bundled filter/transition/mask catalogs (see Bundled effect catalog).
License & credits
MIT © 2026 James Aldrin Boncales. Contributions and issues welcome. If this saves you time, a link back to jmsldrn.com is appreciated — not required.
Always keep a copy of important drafts before batch-editing. This software is provided "as is", without warranty.
Available Tools
28 toolscapcut_add_audioC
Add an audio clip at a time on a track.
Inputs: file (required), draft (required), posX, posY, +10 more.
capcut_add_audio_fadeA
Set fade-in/fade-out duration on an audio (or audio-carrying) segment. Omit either to leave it unchanged.
Inputs: draft (required), segmentId (required), fadeInSec, fadeOutSec.
capcut_add_filterA
Attach a real CapCut filter (from capcut_list_filters) to a segment, replacing any filter already on it. intensity is 0-1 (default: the filter's own default).
Inputs: name (required), draft (required), segmentId (required), intensity.
capcut_add_imageC
Add an image at a time on a track.
Inputs: file (required), draft (required), posX, posY, +10 more.
capcut_add_keyframeA
Add/replace a keyframe on a segment property at a time, creating real per-property animation (not a static value). Call twice with different atSec/value on the same property to animate between them. property must be one of: KFTypePositionX, KFTypePositionY, KFTypeRotation, KFTypeScaleX, KFTypeScaleY, UNIFORM_SCALE, KFTypeAlpha, KFTypeSaturation, KFTypeContrast, KFTypeBrightness, KFTypeVolume.
Inputs: atSec (required), draft (required), value (required), property (required), +1 more.
capcut_add_maskA
Attach a mask shape (from capcut_list_masks) to a segment, replacing any mask already on it. center/width/height/rotation/feather/roundCorner are fractions (0-1) unless noted.
Inputs: name (required), draft (required), segmentId (required), width, +7 more.
capcut_add_stickerA
Add a sticker by CapCut resource_id (get one by inspecting a draft where you or the user already placed that sticker once -- there is no bundled sticker catalog, CapCut's sticker library is too large/volatile to ship). Placed on a new or existing sticker track.
Inputs: draft (required), resourceId (required), posX, posY, +10 more.
capcut_add_textC
Add a text overlay. Requires a text template (a draft with a text layer; see CAPCUT_TEMPLATE_DRAFT).
Inputs: text (required), draft (required), posX, posY, +5 more.
capcut_add_trackC
Add a new track (video | audio | text | sticker).
Inputs: draft (required), name, type.
capcut_add_transitionA
Attach a real CapCut transition (from capcut_list_transitions) on this segment, applied between it and whichever segment follows immediately on the same track.
Inputs: name (required), draft (required), segmentId (required), durationSec.
capcut_add_videoB
Add a video clip at a time on a track. Session edit; call capcut_save to persist.
Inputs: file (required), draft (required), posX, posY, +10 more.
capcut_clone_draftA
Copy a draft folder to a new name (valid scaffolding). empty:true clears all clips/tracks for a fresh build.
Inputs: base (required), newName (required), empty.
capcut_delete_segmentA
Remove a segment. With ripple:true, every later segment (on this track, or every track if rippleAllTracks:true) shifts earlier to close the gap instead of leaving dead space.
Inputs: draft (required), segmentId (required), ripple, rippleAllTracks.
capcut_discardA
Drop unsaved session edits and reload the draft from disk.
Inputs: draft (required).
capcut_list_draftsA
List CapCut drafts in /root/Movies/CapCut/User Data/Projects/com.lveditor.draft with duration and lock status.
Inputs: no named parameters.
capcut_list_filtersA
Search the bundled catalog of 474 real CapCut filters by name (case/space-insensitive substring). Omit query to see the first matches.
Inputs: query.
capcut_list_masksA
List the 9 available mask shapes.
Inputs: no named parameters.
capcut_list_transitionsA
Search the bundled catalog of 116 real CapCut transitions by name (case/space-insensitive substring). Omit query to see the first matches.
Inputs: query.
capcut_move_segmentB
Move a segment to a new start time and optionally another track.
Inputs: atSec (required), draft (required), segmentId (required), trackIndex.
capcut_raw_patchA
Advanced escape hatch: deep-merge a JSON patch into draft_content (undocumented ops). Use with care.
Inputs: draft (required), patch (required).
capcut_read_timelineA
Read a draft: canvas, fps, tracks and every segment (id, media, times, layer). Reflects any pending unsaved edits from this session.
Inputs: draft (required).
capcut_remove_keyframesA
Remove all keyframes for one property on a segment (it reverts to a static value from clip/set_props).
Inputs: draft (required), property (required), segmentId (required).
capcut_saveA
Write session edits to disk (backs up .mcpbak, validates). Refuses if CapCut is open unless force:true.
Inputs: draft (required), force.
capcut_set_propsC
Set transform / opacity / volume / speed / visibility on a segment.
Inputs: draft (required), segmentId (required), posX, posY, +8 more.
capcut_split_segmentB
Split a segment into two at a timeline time.
Inputs: atSec (required), draft (required), segmentId (required).
capcut_trim_segmentA
Change a segment start / duration / source in-point (seconds). With ripple:true, every later segment (on this track, or every track if rippleAllTracks:true) shifts by the resulting time change instead of leaving a gap or an overlap.
Inputs: draft (required), segmentId (required), atSec, durSec, +3 more.
capcut_undoA
Undo the last edit in this session (up to 20 steps back). Does not affect anything already saved to disk.
Inputs: draft (required).
capcut_validateB
Check the (in-session) draft for overlaps, duplicate ids/render_index, missing media.
Inputs: draft (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
Every tool maps to a distinct resource/action (drafts, masks, filters, transitions, segments, keyframes, session state), and overlapping operations are differentiated by clear object nouns (e.g., add_video vs add_track; set_props vs add_keyframe). The only wildcard is raw_patch, but it is explicitly framed as an escape hatch rather than a competing workflow.
Tools consistently use capcut_<verb>_<noun> in snake_case (list_drafts, add_video, trim_segment, save), making the API predictable. Minor deviations like capcut_read_timeline instead of list/get and the adjective-noun raw_patch prevent a perfect score.
At 28 tools, the server exceeds the comfortable range and will feel heavy for an agent to discover and select from, even though most tools are distinct. A more consolidated surface would be more appropriate for the apparent scope.
The toolkit covers the core editing lifecycle: draft discovery/cloning, timeline inspection, adding/removing/transforming segments, effects, keyframes, and session persistence/validation. Gaps like no explicit track deletion, no direct effect removal (only replacement), and no sticker catalog create minor workarounds but not dead ends.
Related MCP Connectors
CapCut MCP server for ChatGPT, Claude and any AI agent: list drafts, export draft, add auto captions, share draft for review, invite members to a space, set member role, transfer editing permission and search templates in your own CapCut account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to CapCut yourself; Cotlet does not store your password and you need no CapCut API key. About the official CapCut API: Partly. CapCut has an official plugin for the ChatGPT desktop app that builds drafts and adds captions, effects and templates (capcut.com, checked 6 Nov 2026). Setup and FAQ: https://cotlet.dev/integrations/capcut-api-mcp-server
Open-source AI video editor: cut, caption, clip and animate real Revline projects from your agent.
Validate video cut plans and parse timed subtitles for Laqta’s local browser video editor.
AI video editor for agents and humans: timeline, captions, color, audio and generation as MCP tools.
Related MCP Servers
- FlicenseAqualityDmaintenanceCreates and edits CapCut desktop drafts locally by writing project files, enabling timeline manipulation through MCP tools.7-
- AlicenseBqualityCmaintenanceAn MCP server for inspecting and editing CapCut Desktop draft projects through local, version-safe timeline operations.53MIT
- AlicenseBqualityBmaintenanceEnables AI to create and edit local Jianying/CapCut draft projects on macOS from videos, images, audio, and text, supporting editable subtitles, keyframes, motion presets, and batch operations via MCP tools.2214MIT
- AlicenseAqualityCmaintenanceEnables AI agents to programmatically edit CapCut Desktop and JianYing Pro projects by directly manipulating native draft files, supporting multi-track timelines, keyframing, transitions, subtitles, and headless previews.246MIT