capcut-mcp

An MCP server that lets Claude read and edit CapCut desktop draft projects — add/move/trim/split clips, text, audio, images; set transforms; validate; save. It works by cloning real segment/material templates out of an existing draft (the only reliable way to produce valid CapCut JSON), and it saves atomically with a backup and a validation pass.

Free & open source (MIT). Built by James Aldrin Boncales for editors who want Claude to drive CapCut for them.

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)

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. Default 0723 is the author’s own draft and won’t exist on your machine — set this to one of your drafts that has a text layer, or the capcut_add_text tool won’t work. (Everything else works without it.)

Install

git clone https://github.com/JmsLdrn/capcut-mcp
cd capcut-mcp
npm install

Then 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)

1. Close CapCut on the draft you want to edit. CapCut autosaves on a timer; writing while it’s open gets clobbered. capcut_save refuses if CapCut is running or the draft’s .locked file is present (override with force: true only if you know it’s safe).
2. Edits are a session: capcut_add_* / capcut_move_* etc. accumulate in memory. Nothing hits disk until capcut_save.
3. capcut_save writes draft_content.json (+ meta) atomically after making a .mcpbak backup, and runs capcut_validate.
4. Reopen the draft in CapCut.