capcut-mcp-server
README.md
# CapCut Desktop MCP Server & Agent Skills ๐ฌ
[](https://github.com/AiPersonacademy/capcut-mcp/actions/workflows/ci.yml)
[](https://github.com/AiPersonacademy/capcut-mcp)
[](https://github.com/AiPersonacademy/capcut-mcp)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://modelcontextprotocol.io/)
[](https://www.typescriptlang.org/)
[](CONTRIBUTING.md)
> **Enterprise-grade Model Context Protocol (MCP) server & Agent Skills for CapCut Desktop & JianYing Pro (ๅชๆ )**.
> Programmatic video editing, multi-track timeline construction, Quad Ease keyframing, and viral typography for **Claude Desktop**, **Cursor AI**, **Google Antigravity**, **Cline**, and **Windsurf**.
---
## ๐ Table of Contents
- [Why CapCut MCP?](#-why-capcut-mcp)
- [Architecture & Direct AST Engine](#-architecture--direct-ast-engine)
- [Key Features](#-key-features)
- [Quick Start](#-quick-start)
- [Client Configuration](#-client-configuration)
- [Claude Desktop](#claude-desktop)
- [Cursor AI](#cursor-ai)
- [Google Antigravity](#google-antigravity)
- [Windsurf & Cline](#windsurf--cline)
- [MCP Tools Reference (24 Atomic Tools)](#-mcp-tools-reference-24-atomic-tools)
- [Viral Typography Engine](#-viral-typography-engine)
- [AI Agent Skills & Editorial Playbooks](#-ai-agent-skills--editorial-playbooks)
- [Testing & Quality Assurance](#-testing--quality-assurance)
- [Contributing](#-contributing)
- [License](#-license)
---
## ๐ก Why CapCut MCP?
Traditional AI video editing attempts rely on brittle GUI automation: simulating mouse clicks, keystrokes, and window focusing that fail when UI elements shift or screen resolutions vary.
**CapCut MCP takes an entirely different approach:**
- **Direct AST Manipulation**: It reads and writes directly to CapCut's native `draft_content.json` Abstract Syntax Tree (AST).
- **Instant & Deterministic**: Timelines, multi-track sequences, cuts, speed ramps, and keyframes apply in milliseconds without opening the GUI.
- **Cross-Platform**: Works natively with both **CapCut Global** and **JianYing Pro (ๅชๆ )** on Windows and macOS.
- **Zero Window Focus**: Edits run cleanly in the background while you continue working.
---
## ๐ Architecture & Direct AST Engine
```
User Prompt (e.g. "Cut dead air, add viral captions, punch zoom on keywords")
โ
โผ
AI Agent (Claude Desktop / Cursor / Antigravity)
โ
โผ (Model Context Protocol JSON-RPC)
capcut-mcp-server
โ
โโโโโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโ
โผ โผ โผ
CapCut Path Resolver Media Probe (FFprobe) Draft Manager
(CapCut Global / JianYing) โ
โผ
Draft Builder
(Native AST Generator)
โ
โผ
CapCut Project Directory
(%LOCALAPPDATA%/CapCut/...)
โ
โผ
Native CapCut Project Ready
```
1. **`paths.ts`**: Dynamically detects CapCut Global or JianYing Pro directories without hardcoded user paths.
2. **`draft-builder.ts`**: Pure deterministic constructor for clips, keyframes, transitions, text materials, and multi-track audio.
3. **`draft-manager.ts`**: High-level timeline orchestrator providing safe atomic file writes and project registration.
4. **`preview-renderer.ts`**: Generates headless proxy MP4 previews via FFmpeg without launching the CapCut application.
---
## โจ Key Features
- ๐ฌ **24 Atomic Video Editing Tools**: Complete programmatic control over projects, multi-track timelines, transformations, speed scaling, audio fades, subtitles, and keyframes.
- โก **Multi-Track Orchestration**: Base A-roll, overlay B-roll layers, background music with audio ducking (-12dB), sound effects, and text caption tracks.
- ๐ฅ **Viral Typography Engine**: Built-in support for high-retention short-form styles (Style 6 Glow Pop, Style 7 Hero Typography, -1.0 metric tracking, ambient drop shadows, and scale pop animations).
- ๐ **Mathematical Keyframing & Easing**: Quad Ease Out curves, kinetic punch-in zooms, smooth opacity transitions, and position pans.
- ๐ฏ **Synchronized Subtitles**: Parse and import standard SRT files directly into formatted native CapCut text layers.
- ๐ผ๏ธ **Fast Headless Previews**: Render fast proxy preview MP4s using FFmpeg without opening the CapCut GUI.
- ๐ค **Production Agent Skills Included**: Battle-tested prompt playbooks and references in `skills/capcut/` covering Walter Murch's Rule of Six, B-roll sourcing, and Quad Easing.
---
## ๐ Quick Start
### 1. Global Installation (Recommended)
```bash
# Run directly via npx
npx capcut-mcp-server
# Or install globally via npm
npm install -g capcut-mcp-server
```
### 2. Run from Source
```bash
git clone https://github.com/AiPersonacademy/capcut-mcp.git
cd capcut-mcp
npm install
npm run build
npm test
npm start
```
---
## ๐ Client Configuration
### Claude Desktop
Add this configuration to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"capcut": {
"command": "npx",
"args": ["-y", "capcut-mcp-server"]
}
}
}
```
*Config file locations:*
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
---
### Cursor AI
Add to your `.cursor/mcp.json` or global MCP settings:
```json
{
"mcpServers": {
"capcut": {
"command": "npx",
"args": ["-y", "capcut-mcp-server"]
}
}
}
```
---
### Google Antigravity
Add to your `mcp_config.json`:
```json
{
"mcpServers": {
"capcut": {
"command": "node",
"args": ["<ABSOLUTE_PATH_TO_CAPCUT_MCP>/dist/src/index.js"]
}
}
}
```
---
### Windsurf & Cline
Configure the stdio command:
```json
{
"mcpServers": {
"capcut": {
"command": "npx",
"args": ["-y", "capcut-mcp-server"]
}
}
}
```
---
## ๐ ๏ธ MCP Tools Reference (24 Atomic Tools)
| Tool Name | Category | Description | Key Parameters |
|:---|:---|:---|:---|
| `capcut_list_projects` | Projects | Lists all local CapCut projects with duration, resolution, and track counts | *None* |
| `capcut_get_project` | Projects | Fetches the full timeline structure, tracks, media materials, and duration | `project_name_or_id` |
| `capcut_create_project` | Projects | Creates a new project draft with custom canvas dimensions (e.g. 1080x1920) | `name`, `width`, `height`, `ratio`, `fps` |
| `capcut_duplicate_project` | Projects | Duplicates an existing project draft under a new name | `source_project_name_or_id`, `new_project_name` |
| `capcut_delete_project` | Projects | Safely deletes a project folder from CapCut storage | `project_name_or_id` |
| `capcut_open_app` | Projects | Launches CapCut Desktop or opens project directory in Explorer | `project_name_or_id` |
| `capcut_add_video_clip` | Timeline | Inserts or appends a video clip onto any track index | `project_name_or_id`, `file_path`, `track_index`, `start_time` |
| `capcut_add_audio_clip` | Audio | Adds background music or voiceover with volume control | `project_name_or_id`, `file_path`, `track_index`, `volume` |
| `capcut_add_sound_effect` | Audio | Inserts SFX (whooshes, pops, risers, impacts) at exact timestamps | `project_name_or_id`, `file_path`, `start_time` |
| `capcut_add_audio_fade` | Audio | Applies smooth fade-in and fade-out volume curves | `project_name_or_id`, `track_index`, `clip_index`, `fade_in`, `fade_out` |
| `capcut_trim_clip` | Editing | Trims in/out source points and target duration of an existing clip | `project_name_or_id`, `track_index`, `clip_index`, `source_start`, `source_duration` |
| `capcut_split_clip` | Editing | Splits a clip at an exact timeline timestamp | `project_name_or_id`, `track_index`, `clip_index`, `split_timestamp` |
| `capcut_remove_clip` | Editing | Removes a specific clip from a timeline track | `project_name_or_id`, `track_index`, `clip_index` |
| `capcut_set_clip_transform` | Transform | Adjusts 2D position `(x, y)`, scale multiplier, and rotation degrees | `project_name_or_id`, `track_index`, `clip_index`, `x`, `y`, `scale`, `rotation` |
| `capcut_set_clip_speed` | Transform | Modifies speed multiplier (0.1x to 100.0x) with pitch preservation | `project_name_or_id`, `track_index`, `clip_index`, `speed`, `change_pitch` |
| `capcut_add_keyframe` | Animation | Adds keyframe animation for scale, position, or opacity | `project_name_or_id`, `track_index`, `clip_index`, `property`, `time_offset`, `value` |
| `capcut_add_transition` | Transitions | Adds native video transitions (dissolve, push, zoom, wipe) | `project_name_or_id`, `track_index`, `clip_index`, `transition_type`, `duration` |
| `capcut_add_text` | Text | Injects static text, titles, or lower thirds | `project_name_or_id`, `text`, `start_time`, `duration`, `font_size`, `color` |
| `capcut_add_subtitles` | Text | Parses and imports complete SRT subtitle files into text tracks | `project_name_or_id`, `srt_content`, `font_size`, `color` |
| `capcut_add_viral_caption` | Text | Adds viral dynamic caption with accent words and hover-pop animations | `project_name_or_id`, `text`, `power_words`, `accent_color`, `font_family` |
| `capcut_add_sticker` | Graphics | Places graphic stickers or overlays on the timeline | `project_name_or_id`, `sticker_id`, `start_time`, `duration` |
| `capcut_create_video_bridge` | Sequencing | Creates a multi-track sequenced project with video plates & audio ducking | `project_name`, `video_plate_path`, `audio_tracks`, `subtitles_srt_path` |
| `capcut_get_media_info` | Utilities | Probes video/audio resolution, duration, codecs, and framerate | `file_path` |
| `capcut_generate_preview` | Utilities | Generates a fast proxy preview MP4 via headless FFmpeg | `project_name_or_id`, `output_path`, `resolution` |
---
## ๐จ Viral Typography Engine
Short-form retention depends on visual stimulation and dynamic typography. CapCut MCP comes with pre-calibrated viral styles accessible via `capcut_add_viral_caption`:
### Style 6: Glow Pop
- **Font**: Montserrat ExtraBold / Impact
- **Primary Color**: High-saturation electric yellow (`#FFE600`) or lime (`#00FF66`)
- **Stroke**: Heavy black outline (`#000000`, width `12-16`)
- **Drop Shadow**: Ambient soft blur
- **Pop Motion**: Scale burst (1.15x -> 1.0x) over 120ms at word boundary
### Style 7: Hero Typography
- **Character Spacing**: `-1.0` metric tracking (tight, cinematic feel)
- **Casing**: Uppercase
- **Shadow Offset**: `(26, 26)` with 85% opacity
- **Color Accent**: Single focal word highlighted in cyan (`#00E5FF`) or electric magenta (`#FF0055`)
---
## ๐ค AI Agent Skills & Editorial Playbooks
This repository includes a dedicated Agent Skill located at [`skills/capcut/SKILL.md`](skills/capcut/SKILL.md).
When connected to an AI agent, the agent can autonomously follow the **Autonomous Editing Playbook**:
1. **Probe**: Inspect raw files with `capcut_get_media_info`.
2. **Scaffold**: Create the project canvas with `capcut_create_project`.
3. **Assemble A-Roll**: Place primary speech clips on Track 0 with `capcut_add_video_clip`.
4. **Synchronize Subtitles**: Inject timed captions with `capcut_add_subtitles` or kinetic titles with `capcut_add_viral_caption`.
5. **Overlay B-Roll**: Insert relevant visual cutaways on Track 1 with punch-in zoom keyframes.
6. **Sound Design**: Add background music (ducked to -12dB) with `capcut_add_audio_clip` and impact transients with `capcut_add_sound_effect`.
7. **Review**: Generate an instant proxy preview with `capcut_generate_preview` or open CapCut Desktop with `capcut_open_app`.
For comprehensive editorial reference manuals, see:
- [CapCut Master Manual](skills/capcut/references/capcut_master_manual.md)
- [B-Roll Production Manual](skills/capcut/references/broll_production_manual.md)
---
## ๐งช Testing & Quality Assurance
The test suite validates timeline calculations, AST segment generation, track collisions, speed scaling, and SRT subtitle ingestion:
```bash
npm test
```
```
โถ CapCut MCP Server - Comprehensive Suite
โ SrtParser parses standard SRT format accurately (3.0ms)
โ DraftManager creates a 9:16 project and registers in root meta (46.1ms)
โ MediaProbe and addVideoClip with synthetic video (219.5ms)
โ DraftManager adds audio clip (133.6ms)
โ DraftManager sets clip transform (24.3ms)
โ DraftManager trims existing clip (16.4ms)
โ DraftManager adds transition to clip (27.2ms)
โ DraftManager adds keyframe to clip (16.5ms)
โ DraftManager adds sticker to project (25.0ms)
โ DraftManager renders fast proxy preview via ffmpeg (409.5ms)
โ DraftManager adds text overlays to a project (19.8ms)
โ DraftManager adds synchronized subtitles from SRT (22.8ms)
โ DraftManager splits an existing clip accurately (25.2ms)
โ DraftManager sets clip speed and preserves pitch (26.8ms)
โ DraftManager adds audio fade-in and fade-out (25.1ms)
โ DraftManager adds viral caption with Aeovisuals styling (23.4ms)
โ DraftManager creates video bridge draft (203.1ms)
โ DraftManager adds transient sound effect (96.8ms)
โ DraftManager duplicates a project (22.3ms)
โ DraftManager deletes a project safely (13.1ms)
โ CapCut MCP Server - Comprehensive Suite (2805ms)
โน tests 21 | pass 21 | fail 0
```
---
## ๐ค Contributing
Contributions are warmly welcomed! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on development workflow, code style, and PR submissions.
---
## ๐ License
Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for details.
TDQS
A3.7/5.0
Scored across 24 tools
Disambiguation5/5
Each tool targets a distinct action on a distinct entity (project, clip, audio, text, effect). The few related categories (text vs subtitles vs viral caption; audio clip vs sound effect vs fade) are clearly differentiated by descriptions. No two tools appear to do the same job.
Naming Consistency5/5
All 24 tools follow a uniform `capcut_<verb>_<noun>` snake_case convention. Verbs are consistent (get, list, create, add, set, remove, split, etc.) and nouns clearly identify the target. No mixed casing or stylistic inconsistencies.
Tool Count4/5
At 24 tools, the server is on the heavier side but the CapCut editing domain is broad enough to justify the count. Each tool serves a specific editing or project-management function, and there's no obvious redundancy. Slightly above the ideal 3-15 range but not bloated.
Completeness4/5
The tool surface covers project lifecycle (create, read, duplicate, delete), clip management (add, remove, trim, split, speed, transform, keyframe), and media additions (audio, text, subtitles, stickers, transitions, SFX). Some minor gaps like setting audio volume directly or a final export tool, but core editing workflows are supported and workarounds exist.
Maintenance
ActivityMaintained
ResponsivenessNo issues