Skip to main content
Glama

capcut-mcp

An MCP server that assembles CapCut International projects and generates the assets CapCut cannot make itself, so an editor opens a timeline that is mostly done instead of an empty one.

Independent and unofficial. Not affiliated with ByteDance or CapCut. It works by reading and writing CapCut's local project files, a private and undocumented format. Use on projects you can afford to have backed up.

Status: early. Verified by hand on CapCut 9.1.0 (Windows). Every write tool is gated behind check_compatibility, and restyle_captions has a dryRun mode.


What it is, and what it is not

Is: a draft compiler. Cuts, captions, music, titles and code-driven overlays assembled into a real CapCut project.

Is not: a renderer, and not a replacement for the editor. CapCut's AI features — auto-captions, auto-reframe, cloud effects — run on ByteDance servers. A project file can only reference resources that already exist in their catalogue. This tool cannot invoke them, and will not pretend otherwise.

The split it is built around: the machine does assembly, the human does taste. Uniform caption styling across a whole video is assembly. Masking, keyframe easing and colour grading are taste.


Related MCP server: capcut-mcp

Requirements

  • Node.js ≥ 20

  • CapCut International (app_source: "cc"). JianYing is not supported — from 6.0 it encrypts the project on every save, which makes round-trip editing impossible.

  • ffmpeg / ffprobe — optional for reading, required for overlay rendering

  • CapCut must be closed when writing. The editor holds the project in memory and overwrites the file on close.


Setup

1. Install and build

git clone https://github.com/yabdulaziz2009-dev/capcut-mcp.git
cd capcut-mcp
npm install
npm run build          # compiles src/ -> dist/

Optional, and only if you want render_overlay / compose_overlay — it pulls a headless browser (~hundreds of MB):

npm install --prefix remotion

2. Register the server with your MCP client

The server speaks stdio and takes no arguments beyond its own path. Use the absolute path to dist/index.js.

Claude Code — one command:

claude mcp add capcut -- node /absolute/path/to/capcut-mcp/dist/index.js

Claude Desktop — claude_desktop_config.json (%APPDATA%\Claude\ on Windows, ~/Library/Application Support/Claude/ on macOS):

{
  "mcpServers": {
    "capcut": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/absolute/path/to/capcut-mcp/dist/index.js"]
    }
  }
}

On Windows use forward slashes in the JSON, or escape the backslashes (C:\\Users\\…).

Restart the client, then ask it to list your CapCut projects. If list_projects returns your drafts, the server is wired up.

3. Where projects are read from

The local draft store is found automatically:

OS

Path

Windows

%LOCALAPPDATA%\CapCut\User Data\Projects\com.lveditor.draft

macOS

~/Movies/CapCut/User Data/Projects/com.lveditor.draft

Every tool also accepts an explicit project path — either the project folder or its draft_content.json.

Verify

npm test           # 32 unit tests, no CapCut install needed
npm run typecheck

Troubleshooting

Symptom

Cause

Tools missing after restart

Path in the config is relative, or npm run build was never run

refuse: editor is running

CapCut is open — close it, it rewrites the draft on exit

refuse: JianYing draft

Encrypted format, not supported (see above)

render_overlay fails

ffmpeg not on PATH, or npm install --prefix remotion was skipped

Changes vanish

The project was open in CapCut during the write


Tools

Tool

What it does

Writes?

list_projects

CapCut projects in the local draft store

no

inspect_project

Duration, tracks, subtitles as readable text, populated material buckets

no

check_compatibility

ok / warn / refuse verdict before any write

no

restyle_captions

One style across every caption at once, plus an entrance animation

yes

import_subtitles

An SRT file (or raw SRT text) as a styled caption track, with keyword highlighting

yes

render_overlay

Animated motion graphics with a real alpha channel (ProRes 4444)

no

add_overlay

Place a rendered clip on its own track

yes

compose_overlay

Render and place in one call

yes

restyle_captions

The most repetitive job in short-form editing: the same outline, shadow and plate on every caption, set by hand one segment at a time.

Presets: bold-outline (white on heavy black stroke — the shorts default), boxed (rounded dark plate), accent (brand colour with dark outline). A preset can be nudged field by field rather than replaced.

Supported: size, colour, weight, opacity, outline, shadow (colour, angle, distance, blur), background plate, entrance/exit animation from 76 upstream slugs.

Not supported — and it says so instead of pretending: font family and on-screen position. Neither is reachable through capcut-cli; see GATE0-FINDINGS.md §6.

Re-running is safe: captions that already carry an animation keep it and are reported, because upstream can add an animation but not replace one.

render_overlay — the differentiator

CapCut cannot author code-driven motion graphics; editors leave for Remotion and come back with a transparent clip. This closes that loop.

Kinds: lower-third (name bar), title-card (centred statement), callout (pill badge). Text, colours, size, duration and exit timing are parameters — no code is generated per overlay.

Output is ProRes 4444, yuva444p10le — verified to carry a genuine alpha channel (93–96% of pixels fully transparent on the shipped kinds), not a black background.

Confirmed end-to-end on CapCut 9.1 / Windows: the rendered overlay was placed on its own track and the footage showed through its transparent areas in the editor.

npm install --prefix remotion     # one-time, pulls a browser (~hundreds of MB)

Requires ffmpeg. A 2.5-second 1080×1920 overlay renders in ~17 s.

The Remotion project lives in remotion/ as a sibling package, not a dependency of the server, so installing capcut-mcp does not drag a browser along for the tools that never need one.

Always run check_compatibility first. It refuses on JianYing drafts, a running editor, an upstream write-guard block, or pre-existing integrity errors — and warns about untested CapCut versions, diverged storage mirrors and missing binaries.

Version support

Verified by hand on CapCut 9.1.0 (Windows): an externally written text segment survived being opened in the editor. Details and the defects found along the way are in GATE0-FINDINGS.md.

CapCut 9.x has no upstream test fixture, so check_compatibility reports it as untested even though it works here. That is deliberate: the format is private and can change without warning, and an honest warning beats a silent corruption.

Credit

Draft reading and writing is done by capcut-cli (MIT), which handles the transactional multi-file write CapCut 9.x needs — the modern layout keeps a template-2.tmp mirror beside draft_content.json, and both must stay in sync. This project adds the MCP layer, workflow-level composites, and the Remotion overlay bridge.

Licence

MIT.

Author

Built by Abdulaziz Yakubov — Full Stack developer & SEO, Tashkent. GitHub · LinkedIn · DEV

Available Tools

8 tools
add_overlayPlace a rendered overlay on the timelineA

Adds an already-rendered clip to a CapCut project on its own track. Requires CapCut to be closed.

Inputs: file (required), project (required), startSeconds (required), trackName, +1 more.

check_compatibilityCheck whether a project is safe to writeA

Verdict (ok / warn / refuse) before any modification: CapCut vs JianYing, upstream write guard, whether the editor is running, storage-mirror agreement, existing lint errors, and availability of ffmpeg/ffprobe. Run this before writing.

Inputs: project (required).

compose_overlayRender an overlay and place it in one stepA

Renders a transparent overlay and adds it to the project at the given time. The common case — use render_overlay separately when the same graphic is reused across projects.

Inputs: text (required), project (required), startSeconds (required), fps, +9 more.

import_subtitlesImport an SRT as a styled caption trackA

Turns an SRT file — or raw SRT text — into a text track with one segment per cue, styled in the same pass. Presets: bold-outline, boxed, accent. Keyword highlighting colours chosen words inside every caption (whole-word, case-insensitive), which editors otherwise do by hand. Byte offsets are correct for Cyrillic, Uzbek and emoji. Requires CapCut to be closed.

Inputs: project (required), path, style, preset, +5 more.

inspect_projectInspect a CapCut projectA

Reads a project: duration, resolution, tracks, subtitles as readable text, and which material buckets are populated. Read-only.

Inputs: project (required).

list_projectsList CapCut projectsA

Lists CapCut projects found in the local draft store, with folder, path and last-modified time.

Inputs: no named parameters.

render_overlayRender a transparent motion-graphics overlayA

Renders an animated overlay with a real alpha channel (ProRes 4444) using Remotion — motion graphics CapCut cannot author itself. Returns the file path; place it with add_overlay. Requires ffmpeg. Rendering takes tens of seconds.

Inputs: text (required), fps, kind, width, +7 more.

restyle_captionsApply one caption style across the projectA

Applies one style — outline, shadow, background plate, opacity, size, colour, weight — and optionally an entrance animation to every caption at once. This is the job editors otherwise do by hand on every video. Presets: bold-outline, boxed, accent. Animation slugs come from 'capcut enums --text-intros' (typewriter, pop-up, glitch, fade-in, …). NOT supported upstream: font family and on-screen position — those stay manual. Requires CapCut to be closed; use dryRun to preview.

Inputs: project (required), style, dryRun, preset, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 8 tools

    Disambiguation4/5

    Each tool targets a distinct resource/action, but add_overlay and compose_overlay overlap in purpose since compose also adds. The descriptions clarify the distinction, so confusion is unlikely but possible.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (list_projects, add_overlay, import_subtitles). No mixed conventions or vague verbs.

    Tool Count5/5

    8 tools is well-scoped for a CapCut editing server. Each tool covers a distinct operation without redundancy or bloat.

    Completeness4/5

    The set covers common workflows: listing, inspecting, compatibility checking, adding/rendering overlays, restyling captions, and importing subtitles. Minor gaps exist like removing overlays or editing individual captions, but core tasks are covered.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides MCP servers for AI-driven video editing. Enables offline editing of CapCut drafts and remote control of Adobe Premiere Pro via UXP plugin, with shared media analysis for beat detection and transcription.
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      An MCP server that reads and builds CapCut projects locally, enabling natural language queries about project contents, missing media, and creation of new edits including beat-synced cuts.
      6
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to build CapCut video draft projects on disk — adding video and image clips, audio with fades, text overlays, SRT subtitles, filters, transitions, animations and keyframes, then saving the draft for editing and opening in CapCut. It also lists existing drafts, browses available effects and fonts, and summarizes track, duration and segment details.
      MIT