Skip to main content
Glama

CapCut Desktop MCP Server & Agent Skills 🎬

CI GitHub Stars GitHub Forks License: MIT Node.js Version Model Context Protocol TypeScript PRs Welcome

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


Related MCP server: capcut-mcp

πŸ’‘ 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

# Run directly via npx
npx capcut-mcp-server

# Or install globally via npm
npm install -g capcut-mcp-server

2. Run from Source

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:

{
  "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:

{
  "mcpServers": {
    "capcut": {
      "command": "npx",
      "args": ["-y", "capcut-mcp-server"]
    }
  }
}

Google Antigravity

Add to your mcp_config.json:

{
  "mcpServers": {
    "capcut": {
      "command": "node",
      "args": ["<ABSOLUTE_PATH_TO_CAPCUT_MCP>/dist/src/index.js"]
    }
  }
}

Windsurf & Cline

Configure the stdio command:

{
  "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.

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:


πŸ§ͺ Testing & Quality Assurance

The test suite validates timeline calculations, AST segment generation, track collisions, speed scaling, and SRT subtitle ingestion:

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 for details on development workflow, code style, and PR submissions.


πŸ“„ License

Distributed under the MIT License. See LICENSE for details.

Available Tools

24 tools
capcut_add_audio_clipC

Adds background music, sound effects, or voiceover audio to an audio track.

Inputs: file_path (required), project_name_or_id (required), volume, track_index, +3 more.

capcut_add_audio_fadeA

Adds smooth volume fade-in and/or fade-out envelopes to an audio track segment, eliminating abrupt audio cutoffs in background music or dialogue.

Inputs: segment_id (required), project_name_or_id (required), fade_in_seconds, fade_out_seconds.

capcut_add_keyframeC

Adds an animation keyframe for scale, rotation, translation (x, y), or opacity to a video segment.

Inputs: value (required), property (required), segment_id (required), project_name_or_id (required), +1 more.

capcut_add_sound_effectA

Drops a transient sound effect (whoosh, pop, click, riser impact) at an exact timeline timestamp, aligned with visual keyframes or text pops.

Inputs: sfx_file_path (required), timestamp_seconds (required), project_name_or_id (required), volume, +1 more.

capcut_add_stickerB

Adds an animated sticker or graphic element to the project timeline.

Inputs: sticker_name (required), project_name_or_id (required), x, y, +4 more.

capcut_add_subtitlesA

Batch adds synchronized subtitles / captions from an array of items, an SRT file path, or raw SRT string.

Inputs: project_name_or_id (required), y, font_size, subtitles, +5 more.

capcut_add_textC

Adds a customizable title, lower-third, or text overlay to a text track.

Inputs: text (required), project_name_or_id (required), x, y, +8 more.

capcut_add_transitionA

Adds a transition effect (e.g. Dissolve, Fade to Black, Fade to White, Zoom In) between clips on a video track.

Inputs: segment_id (required), project_name_or_id (required), transition_name, duration_seconds.

capcut_add_video_clipB

Adds a video or image file to a CapCut video track. Media metadata (duration, resolution) is automatically probed.

Inputs: file_path (required), project_name_or_id (required), x, y, +7 more.

capcut_add_viral_captionB

Injects Aeovisuals-calibrated viral typography with -1.0 metric kerning, 26/26 diffuse ambient shadow, custom font, power word scaling/color contrast, and optional Quad Ease hover-up pop keyframes.

Inputs: text (required), project_name_or_id (required), x, y, +8 more.

capcut_create_projectA

Creates a brand new CapCut project draft with canvas resolution and frame rate, registered directly into CapCut Desktop.

Inputs: name (required), fps, ratio, width, +1 more.

capcut_create_video_bridgeA

Orchestrates the Direct Video Track Bridge: creates a CapCut draft around a pre-rendered 60 FPS master video plate (Remotion/WebGL), separates multi-track audio, and auto-imports subtitles into editable tracks.

Inputs: project_name (required), video_plate_path (required), fps, ratio, +2 more.

capcut_delete_projectA

Deletes a CapCut project folder and unregisters it from CapCut. Requires explicit confirmation.

Inputs: confirm (required), project_name_or_id (required).

capcut_duplicate_projectA

Duplicates an existing CapCut project to a new draft with fresh IDs (ideal for creating variations or backups).

Inputs: new_name (required), source_project (required).

capcut_generate_previewA

Renders a fast proxy preview video (.mp4) of a CapCut project using ffmpeg without needing to export from the GUI.

Inputs: project_name_or_id (required), fps, width, height, +1 more.

capcut_get_media_infoA

Inspects video or audio file technical parameters (duration, width, height, fps, codec) using ffprobe.

Inputs: file_path (required).

capcut_get_projectA

Fetches the complete timeline structure, tracks, media materials, and duration of a CapCut project.

Inputs: project_name_or_id (required).

capcut_list_projectsA

Lists all CapCut video projects on this computer, including duration, resolution, track counts, and lock status.

Inputs: no named parameters.

capcut_open_appA

Launches CapCut Desktop on Windows or opens the project folder in Windows Explorer.

Inputs: project_name_or_id.

capcut_remove_clipB

Deletes a specific segment from a project track by its segment ID.

Inputs: segment_id (required), project_name_or_id (required).

capcut_set_clip_speedA

Sets playback speed multiplier (e.g. 0.5x slow-mo, 1.25x talking head, 2.0x time-lapse) with optional pitch preservation so voices do not sound like chipmunks.

Inputs: speed (required), segment_id (required), project_name_or_id (required), preserve_pitch.

capcut_set_clip_transformB

Adjusts scale, rotation, translation position (x, y), or opacity of an existing clip.

Inputs: segment_id (required), project_name_or_id (required), x, y, +3 more.

capcut_split_clipA

Splits a video, audio, or text clip into two linked segments at an exact timeline timestamp (the timeline razor / blade tool). Essential for cutting out pauses, pacing edits, or inserting B-roll.

Inputs: segment_id (required), project_name_or_id (required), split_time_seconds (required).

capcut_trim_clipB

Adjusts the timeline start time or duration of an existing segment by its segment ID.

Inputs: segment_id (required), project_name_or_id (required), new_start_seconds, new_duration_seconds.

Tool Schema Changelog

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

Loading tool schema changelog…

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Enables AI coding agents to programmatically assemble vertical videos and manage local CapCut Desktop drafts, including AI background removal, audio mastering to -14 LUFS or Demucs vocal isolation, music auto-ducking, punch zooms, karaoke captions, PiP proof overlays, hook badges, safe-zone linting, proxy previews, and EN→ES cloning/dubbing. It outputs real CapCut draft JSON ready for review and export.
      17
      2
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables reading and editing CapCut desktop draft projects, including adding/moving/trimming/splitting clips, text, audio, images, filters, transitions, masks, keyframe animation, audio fades, stickers, setting transforms, validation, and saving with backups.
      28
      MIT