capcut-mcp
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
Markdown
[](/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
- {
- "name": "capcut-mcp",
- "description": "CapCut video editing for Claude Code: MCP server + editing skill.",
- "owner": { "name": "batuhantncr16" },
- "plugins": [
- {
- "name": "capcut-mcp",
- "source": "./",
- "description": "Build CapCut desktop projects from Claude: cuts, captions, effects, keyframes, audio."
- }
- ]
- }
README.md · README · 183 lines
- # capcut-mcp
- **Let Claude edit videos in CapCut.** An [MCP](https://modelcontextprotocol.io) server that builds
- real CapCut desktop projects (cuts, B-roll, captions, text animations, effects, keyframes,
- music and SFX) plus a Claude skill that edits like a short-form video pro.
- You describe the video; Claude plans the shot list and assembles the project; you open it in
- CapCut, review, and export.
- [Türkçe README](README.tr.md)
- ```text
- "Make a 30-second Reel from the clips in ~/Desktop/trip, punchy captions, upbeat music"
- -> probe_media x12 -> create_project(9:16) -> add_video x14 -> add_keyframes
- -> add_audio (music + SFX) -> add_subtitles -> add_text (hook, CTA) -> save_project(native)
- -> "Open 'Trip Reel' from CapCut's home screen."
- ```
- ## Features
- - **13 tools**: `create_project`, `probe_media`, `add_video`, `add_image`, `add_audio`,
- `add_text`, `add_subtitles`, `add_effect`, `add_sticker`, `add_keyframes`, `list_options`,
- `save_project`, `list_projects`.
- - **Two output modes**
- - `native`: writes the project straight into CapCut's library, keeping effects, transitions,
- animations and keyframes.
- - `xml` (default): portable FCPXML that CapCut imports natively; always opens, drops
- CapCut-only features (reported as warnings).
- - **Safe by design**: never touches projects it did not create; never rewrites a project after
- CapCut has opened it (saves `<name> v2` instead, because CapCut rejects such drafts); media is
- copied next to the project; nothing is uploaded.
- - **Screen-style coordinates** everywhere (`y = -1` top, `y = 1` bottom); the server converts to
- CapCut's internal convention.
- - **Readable captions**: SRT cues are re-wrapped at word boundaries, so CapCut never splits a
- word across lines.
- - **Guard rails** learned from real projects: effects that render wrongly are refused
- (`Camera_Shake` exports solid black in CapCut 9.8), emoji in text are flagged, and
- `list_options` exposes the exact transition/animation/effect/font names CapCut accepts.
- - **Intro and transition recipes** (`list_options("recipe")`): whip-in, whip-out loop,
- punch-in jump cut, white flash, strobe montage, glitch, blink and black flicker, each with the
- CapCut names, timing, build steps and matching sound effect, measured frame by frame on a
- high-retention Short.
- - **`capcut-editor` skill**: workflow, pacing and retention rules, safe zones, audio levels and a
- pre-save checklist, so Claude edits like a short-form editor instead of a slideshow generator.
- ## Requirements
- - macOS or Windows with **CapCut desktop** (tested with CapCut 9.8 on macOS)
- - Python 3.10+, git, ffmpeg/ffprobe (`brew install ffmpeg`)
- - An MCP client: Claude Code, Claude Desktop, or any MCP-compatible app
- ## Installation
- ### Option A: Claude Code plugin (one step, recommended)
- Installs the MCP server **and** the `capcut-editor` skill:
- ```text
- /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)
- ```bash
- 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:
- ```bash
- claude mcp add capcut -- "$PWD/.venv/bin/capcut-mcp"
- ```
- Claude Desktop (`claude_desktop_config.json`):
- ```json
- {
- "mcpServers": {
- "capcut": { "command": "/ABSOLUTE/PATH/capcut-mcp/.venv/bin/capcut-mcp" }
- }
- }
- ```
- #### Install the skill (Claude Code)
- ```bash
- mkdir -p ~/.claude/skills && cp -R skills/capcut-editor ~/.claude/skills/
- ```
- ## Usage
- Ask in plain language, for example:
- - "Turn the photos on my Desktop into a 20-second 9:16 slideshow with slow zooms and a title."
- - "Cut a 45-second Reel from interview.mp4: best answer first, burned-in captions from
- interview.srt, B-roll from ./broll every 3 seconds."
- - "Assemble a 16:9 YouTube intro from these clips and add lower thirds."
- Claude will probe the media, show a shot list, build the project and tell you which project to
- open in CapCut and what to check before exporting.
- ### Scripting
- All tools are plain Python functions, handy for large builds (hundreds of captions or clips):
- ```python
- import capcut_mcp.server as cc
- pid = cc.create_project("Demo", aspect="9:16")["project_id"]
- cc.add_video(pid, "clip.mp4", end=4, background_blur=3)
- cc.add_keyframes(pid, "main", ["uniform_scale"] * 2, [0, 3.9], ["1.0", "1.1"])
- cc.add_text(pid, "HELLO", start=0, end=2, y=-0.4, size=16, bold=True, border_width=40)
- print(cc.save_project(pid, target="native"))
- ```
- See [`examples/slideshow.py`](examples/slideshow.py) for a complete script.
- ## Configuration
- | Variable | Default | Purpose |
- |---|---|---|
- | `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) |
- | `CAPCUT_XML_DIR` | `~/Movies/CapCut MCP` | where `target="xml"` writes |
- | `CAPCUT_MCP_VECTCUT_DIR` | `vendor/VectCutAPI` | VectCutAPI checkout |
- | `CAPCUT_MCP_STAGING` | system temp dir | scratch space while saving |
- | `CAPCUT_MCP_TEMPLATE` | bundled `native_template/` | empty project saved by your CapCut (see below) |
- ## How it works
- 1. The VectCutAPI / pyJianYingDraft library builds the timeline in memory.
- 2. `save_project(native)` merges that timeline into `native_template/`, an empty project saved by
- CapCut itself, keeping the version-specific keys CapCut expects, then writes the folder into
- CapCut's library with fresh IDs and a cover frame.
- 3. `save_project(xml)` converts the same timeline to FCPXML 1.9, which CapCut imports through its
- own converter.
- If a future CapCut version stops opening native saves, create an empty project in CapCut, close
- it, copy its folder over `src/capcut_mcp/native_template/` (without `draft_cover.jpg`), and strip
- `device_id`, `hard_disk_id` and `mac_address` values before committing. Meanwhile `xml` keeps
- working.
- ## Known issues
- See [docs/known-issues.md](docs/known-issues.md): CapCut-specific behaviour discovered while
- shipping real videos (black frames from some effects, draft re-saving, font coverage, export
- tips).
- ## Development
- ```bash
- .venv/bin/python -m pytest # unit + integration tests (integration needs vendor/)
- .venv/bin/python tests/smoke_stdio.py # drives the server over MCP stdio, all tools
- .venv/bin/ruff check src tests
- ```
- Contributions are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md).
- ## Disclaimer
- Not affiliated with or endorsed by ByteDance or CapCut. CapCut's project format is private and
- may change between versions; the FCPXML path is the stable fallback.
- ## License
- Apache-2.0 (see [LICENSE](LICENSE)). Third-party notices in [NOTICE](NOTICE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.