Skip to content
Back to search

capcut-mcp

MarketplaceWorks with Claude CodeGitHub

CapCut video editing for Claude Code: MCP server + editing skill.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/batuhantncr16--capcut-mcp/badge.svg)](/listings/batuhantncr16--capcut-mcp)

HTML

<a href="/listings/batuhantncr16--capcut-mcp"><img src="/api/listings/batuhantncr16--capcut-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Option A: Claude Code plugin (one step, recommended)

Installs the MCP server **and** the `capcut-editor` skill:

/plugin marketplace add batuhantncr16/capcut-mcp
/plugin install capcut-mcp@capcut-mcp

On Claude Code 2.1.275 or later this also works as a single command: `/plugin install capcut-mcp --marketplace batuhantncr16/capcut-mcp`.

Then run `/reload-plugins` (or start a new session). On its first start the server sets itself up in the plugin's data folder (Python venv + VectCutAPI, about a minute; needs `git`, `python3` and `ffmpeg` on your PATH). If that first connection times out, open `/mcp` and reconnect `capcut`. The skill is available as `/capcut-mcp:capcut-editor` and loads automatically for video-editing requests.

Option B: manual install (any MCP client)

git clone https://github.com/batuhantncr16/capcut-mcp.git
cd capcut-mcp
scripts/setup.sh

`setup.sh` creates `.venv`, fetches [VectCutAPI](https://github.com/sun-guannan/VectCutAPI) at a pinned commit into `vendor/`, applies the patches in `patches/`, installs the package and checks that the server imports.

Register the server

Claude Code:

claude mcp add capcut -- "$PWD/.venv/bin/capcut-mcp"

Claude Desktop (`claude_desktop_config.json`):

{
  "mcpServers": {
    "capcut": { "command": "/ABSOLUTE/PATH/capcut-mcp/.venv/bin/capcut-mcp" }
  }
}

Install the skill (Claude Code)

mkdir -p ~/.claude/skills && cp -R skills/capcut-editor ~/.claude/skills/

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 12 lines
  1. {
  2. "name": "capcut-mcp",
  3. "description": "CapCut video editing for Claude Code: MCP server + editing skill.",
  4. "owner": { "name": "batuhantncr16" },
  5. "plugins": [
  6. {
  7. "name": "capcut-mcp",
  8. "source": "./",
  9. "description": "Build CapCut desktop projects from Claude: cuts, captions, effects, keyframes, audio."
  10. }
  11. ]
  12. }
README.md · README · 183 lines
  1. # capcut-mcp
  2. **Let Claude edit videos in CapCut.** An [MCP](https://modelcontextprotocol.io) server that builds
  3. real CapCut desktop projects (cuts, B-roll, captions, text animations, effects, keyframes,
  4. music and SFX) plus a Claude skill that edits like a short-form video pro.
  5. You describe the video; Claude plans the shot list and assembles the project; you open it in
  6. CapCut, review, and export.
  7. [Türkçe README](README.tr.md)
  8. ```text
  9. "Make a 30-second Reel from the clips in ~/Desktop/trip, punchy captions, upbeat music"
  10. -> probe_media x12 -> create_project(9:16) -> add_video x14 -> add_keyframes
  11. -> add_audio (music + SFX) -> add_subtitles -> add_text (hook, CTA) -> save_project(native)
  12. -> "Open 'Trip Reel' from CapCut's home screen."
  13. ```
  14. ## Features
  15. - **13 tools**: `create_project`, `probe_media`, `add_video`, `add_image`, `add_audio`,
  16. `add_text`, `add_subtitles`, `add_effect`, `add_sticker`, `add_keyframes`, `list_options`,
  17. `save_project`, `list_projects`.
  18. - **Two output modes**
  19. - `native`: writes the project straight into CapCut's library, keeping effects, transitions,
  20. animations and keyframes.
  21. - `xml` (default): portable FCPXML that CapCut imports natively; always opens, drops
  22. CapCut-only features (reported as warnings).
  23. - **Safe by design**: never touches projects it did not create; never rewrites a project after
  24. CapCut has opened it (saves `<name> v2` instead, because CapCut rejects such drafts); media is
  25. copied next to the project; nothing is uploaded.
  26. - **Screen-style coordinates** everywhere (`y = -1` top, `y = 1` bottom); the server converts to
  27. CapCut's internal convention.
  28. - **Readable captions**: SRT cues are re-wrapped at word boundaries, so CapCut never splits a
  29. word across lines.
  30. - **Guard rails** learned from real projects: effects that render wrongly are refused
  31. (`Camera_Shake` exports solid black in CapCut 9.8), emoji in text are flagged, and
  32. `list_options` exposes the exact transition/animation/effect/font names CapCut accepts.
  33. - **Intro and transition recipes** (`list_options("recipe")`): whip-in, whip-out loop,
  34. punch-in jump cut, white flash, strobe montage, glitch, blink and black flicker, each with the
  35. CapCut names, timing, build steps and matching sound effect, measured frame by frame on a
  36. high-retention Short.
  37. - **`capcut-editor` skill**: workflow, pacing and retention rules, safe zones, audio levels and a
  38. pre-save checklist, so Claude edits like a short-form editor instead of a slideshow generator.
  39. ## Requirements
  40. - macOS or Windows with **CapCut desktop** (tested with CapCut 9.8 on macOS)
  41. - Python 3.10+, git, ffmpeg/ffprobe (`brew install ffmpeg`)
  42. - An MCP client: Claude Code, Claude Desktop, or any MCP-compatible app
  43. ## Installation
  44. ### Option A: Claude Code plugin (one step, recommended)
  45. Installs the MCP server **and** the `capcut-editor` skill:
  46. ```text
  47. /plugin marketplace add batuhantncr16/capcut-mcp
  48. /plugin install capcut-mcp@capcut-mcp
  49. ```
  50. On Claude Code 2.1.275 or later this also works as a single command:
  51. `/plugin install capcut-mcp --marketplace batuhantncr16/capcut-mcp`.
  52. Then run `/reload-plugins` (or start a new session). On its first start the server sets itself
  53. up in the plugin's data folder (Python venv + VectCutAPI, about a minute; needs `git`,
  54. `python3` and `ffmpeg` on your PATH). If that first connection times out, open `/mcp` and
  55. reconnect `capcut`. The skill is available as `/capcut-mcp:capcut-editor` and loads
  56. automatically for video-editing requests.
  57. ### Option B: manual install (any MCP client)
  58. ```bash
  59. git clone https://github.com/batuhantncr16/capcut-mcp.git
  60. cd capcut-mcp
  61. scripts/setup.sh
  62. ```
  63. `setup.sh` creates `.venv`, fetches [VectCutAPI](https://github.com/sun-guannan/VectCutAPI) at a
  64. pinned commit into `vendor/`, applies the patches in `patches/`, installs the package and checks
  65. that the server imports.
  66. #### Register the server
  67. Claude Code:
  68. ```bash
  69. claude mcp add capcut -- "$PWD/.venv/bin/capcut-mcp"
  70. ```
  71. Claude Desktop (`claude_desktop_config.json`):
  72. ```json
  73. {
  74. "mcpServers": {
  75. "capcut": { "command": "/ABSOLUTE/PATH/capcut-mcp/.venv/bin/capcut-mcp" }
  76. }
  77. }
  78. ```
  79. #### Install the skill (Claude Code)
  80. ```bash
  81. mkdir -p ~/.claude/skills && cp -R skills/capcut-editor ~/.claude/skills/
  82. ```
  83. ## Usage
  84. Ask in plain language, for example:
  85. - "Turn the photos on my Desktop into a 20-second 9:16 slideshow with slow zooms and a title."
  86. - "Cut a 45-second Reel from interview.mp4: best answer first, burned-in captions from
  87. interview.srt, B-roll from ./broll every 3 seconds."
  88. - "Assemble a 16:9 YouTube intro from these clips and add lower thirds."
  89. Claude will probe the media, show a shot list, build the project and tell you which project to
  90. open in CapCut and what to check before exporting.
  91. ### Scripting
  92. All tools are plain Python functions, handy for large builds (hundreds of captions or clips):
  93. ```python
  94. import capcut_mcp.server as cc
  95. pid = cc.create_project("Demo", aspect="9:16")["project_id"]
  96. cc.add_video(pid, "clip.mp4", end=4, background_blur=3)
  97. cc.add_keyframes(pid, "main", ["uniform_scale"] * 2, [0, 3.9], ["1.0", "1.1"])
  98. cc.add_text(pid, "HELLO", start=0, end=2, y=-0.4, size=16, bold=True, border_width=40)
  99. print(cc.save_project(pid, target="native"))
  100. ```
  101. See [`examples/slideshow.py`](examples/slideshow.py) for a complete script.
  102. ## Configuration
  103. | Variable | Default | Purpose |
  104. |---|---|---|
  105. | `CAPCUT_DRAFTS_DIR` | `~/Movies/CapCut/User Data/Projects/com.lveditor.draft` | CapCut's project library (macOS default; on Windows copy the path from CapCut > Settings > Drafts location) |
  106. | `CAPCUT_XML_DIR` | `~/Movies/CapCut MCP` | where `target="xml"` writes |
  107. | `CAPCUT_MCP_VECTCUT_DIR` | `vendor/VectCutAPI` | VectCutAPI checkout |
  108. | `CAPCUT_MCP_STAGING` | system temp dir | scratch space while saving |
  109. | `CAPCUT_MCP_TEMPLATE` | bundled `native_template/` | empty project saved by your CapCut (see below) |
  110. ## How it works
  111. 1. The VectCutAPI / pyJianYingDraft library builds the timeline in memory.
  112. 2. `save_project(native)` merges that timeline into `native_template/`, an empty project saved by
  113. CapCut itself, keeping the version-specific keys CapCut expects, then writes the folder into
  114. CapCut's library with fresh IDs and a cover frame.
  115. 3. `save_project(xml)` converts the same timeline to FCPXML 1.9, which CapCut imports through its
  116. own converter.
  117. If a future CapCut version stops opening native saves, create an empty project in CapCut, close
  118. it, copy its folder over `src/capcut_mcp/native_template/` (without `draft_cover.jpg`), and strip
  119. `device_id`, `hard_disk_id` and `mac_address` values before committing. Meanwhile `xml` keeps
  120. working.
  121. ## Known issues
  122. See [docs/known-issues.md](docs/known-issues.md): CapCut-specific behaviour discovered while
  123. shipping real videos (black frames from some effects, draft re-saving, font coverage, export
  124. tips).
  125. ## Development
  126. ```bash
  127. .venv/bin/python -m pytest # unit + integration tests (integration needs vendor/)
  128. .venv/bin/python tests/smoke_stdio.py # drives the server over MCP stdio, all tools
  129. .venv/bin/ruff check src tests
  130. ```
  131. Contributions are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md).
  132. ## Disclaimer
  133. Not affiliated with or endorsed by ByteDance or CapCut. CapCut's project format is private and
  134. may change between versions; the FCPXML path is the stable fallback.
  135. ## License
  136. Apache-2.0 (see [LICENSE](LICENSE)). Third-party notices in [NOTICE](NOTICE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.