🎬 CapCut MCP Server

An MCP (Model Context Protocol) server that gives AI assistants full control over CapCut video editing projects. Create projects, import media, add text/subtitles, manage audio, and edit timelines — all through AI-powered tools.

How It Works

AI Assistant  ──MCP Protocol──▶  CapCut MCP Server  ──Read/Write JSON──▶  CapCut Draft Files
                                  (Python/FastMCP)                          (draft_content.json)

CapCut stores every project as a folder with a draft_content.json file. This MCP server reads and writes those files directly. You edit via the AI, then open the project in CapCut to preview and export.

Quick Start

1. Install

# Clone your repository
git clone https://github.com/baizo7/capcut_MCP_server-.git
cd capcut_MCP_server-

# Using pip
pip install -e ".[cli]"

# Or using uv (recommended)
uv pip install -e .

2. Configure your MCP client

Gemini IDE / Antigravity

On Windows, open your Gemini MCP configuration file located at: %USERPROFILE%\.gemini\config\mcp_config.json

Add this to your mcpServers object:

{
  "mcpServers": {
    "capcut": {
      "command": "python",
      "args": ["-m", "capcut_mcp.server"],
      "env": {
        "CAPCUT_DRAFTS_PATH": "C:\\Users\\LENOVO\\AppData\\Local\\CapCut\\User Data\\Projects\\com.lveditor.draft"
      }
    }
  }
}

Note: After saving, restart the IDE for the new server to boot up.

Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "capcut": {
      "command": "python",
      "args": ["-m", "capcut_mcp.server"]
    }
  }
}

Cursor IDE

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "capcut": {
      "command": "python",
      "args": ["-m", "capcut_mcp.server"]
    }
  }
}

3. Start editing!

Once configured, your AI assistant can use commands like:

• "Create a new TikTok project called 'Summer Vibes'"
• "Import all videos from D:\footage\vacation and add them to the timeline"
• "Add subtitles: 'Hello!' at 0-2s and 'Welcome!' at 2-5s"
• "Trim the first clip to start at 3 seconds"

---

🛑 Important Limitations & Workarounds

1. Windows Store Python Sandbox

If you are running the MCP server using Python installed from the Microsoft Store (which is common in Gemini IDE and Cursor), Windows automatically sandboxes writes to AppData\Local.

• The Issue: The AI will create projects perfectly, but Windows hides them from CapCut.
• The Fix: We built an automatic "Sandbox Escape" into the server using PowerShell! However, for best results, we highly recommend changing CapCut's default save location (Settings -> Project -> Save to) to your Documents folder, and updating your CAPCUT_DRAFTS_PATH environment variable to match it.

2. CapCut Does Not "Hot-Reload"

Because we are editing the raw JSON save files on your hard drive behind CapCut's back, CapCut does not instantly update its screen while you are actively editing a timeline.

• To see changes: You must click the "X" in CapCut to return to the Home screen, then click the project again to force CapCut to reload the timeline from the hard drive.
• For new projects: Simply switch tabs (e.g., from "Space" to "Home") to refresh the project list.

---

Configuration

Environment Variable	Description	Default
CAPCUT_DRAFTS_PATH	Path to your CapCut drafts folder	Auto-discovered

Auto-discovery

The server automatically checks these locations for CapCut projects:

• %LOCALAPPDATA%\CapCut\User Data\Projects\com.lveditor.draft
• %LOCALAPPDATA%\CapCut\User Data\Drafts

---

Available Tools (25+)

📁 Project Management

Tool	Description
list_projects	List all CapCut projects on this computer
get_project_info	Detailed project info: tracks, materials, segments
create_project	Create a new empty project (with canvas presets)
duplicate_project	Clone a project as a template
delete_project	Delete a project (requires confirmation)
list_canvas_presets	Show available canvas sizes (landscape, portrait, etc.)

🎥 Media Import

Tool	Description
add_video	Import a video file to the timeline
add_image	Add an image as a still clip
add_media_batch	Batch-import all media from a folder
list_materials	List all assets in a project
remove_material	Remove an asset and its timeline clips

📝 Text & Subtitles

Tool	Description
add_text	Add a text overlay at a specific time
add_subtitles	Bulk-add subtitles from a structured list
update_text_style	Change font, color, size, alignment
update_text_content	Change the text content

🔊 Audio

Tool	Description
add_audio	Add background music or sound effects
set_volume	Adjust volume of a specific clip
mute_track	Mute all clips on a track
unmute_track	Restore volume on a muted track

✂️ Timeline Editing

Tool	Description
trim_clip	Trim a clip's start/end point
split_clip	Split a clip into two parts at a timestamp
move_clip	Move a clip to a new timeline position
delete_clip	Remove a clip from the timeline
reorder_clips	Arrange clips sequentially with optional gaps
set_clip_speed	Change playback speed (slow-mo, fast-forward)

---

Safety Features

• Automatic backups: Every edit creates a .backup of the draft before modifying
• Non-destructive: Delete operations require explicit confirmation
• Validation: All file paths are verified before import

---

Development

# Install in development mode
pip install -e ".[dev]"

# Run tests
python -m pytest tests/ -v

# Test with MCP Inspector (browser-based)
npx -y @modelcontextprotocol/inspector python -m capcut_mcp.server

---

Important Notes

⚠️ Unofficial: This server reverse-engineers CapCut's project format. It is not affiliated with ByteDance.

⚠️ Backups: The server automatically backs up projects before modification, but always keep your own backups of important projects.

⚠️ ffprobe: For accurate video/audio duration detection, install FFmpeg and ensure ffprobe is on your PATH. Without it, the server uses default duration estimates.