CapCutAPI/MCP_Documentation_English.md

CapCut API MCP Server Documentation

Overview

The CapCut API MCP Server is a video editing service based on the Model Context Protocol (MCP), providing complete CapCut video editing functionality interfaces. Through the MCP protocol, you can easily integrate professional-grade video editing capabilities into various applications.

Features

🎬 Core Capabilities

• Draft Management: Create, save, and manage video projects
• Multimedia Support: Video, audio, image, and text processing
• Advanced Effects: Effects, animations, transitions, and filters
• Precise Control: Timeline, keyframes, and layer management

🛠️ Available Tools (11 Tools)

Tool Name	Description	Key Parameters
create_draft	Create new video draft project	width, height
add_text	Add text elements	text, font_size, color, shadow, background
add_video	Add video track	video_url, start, end, transform, volume
add_audio	Add audio track	audio_url, volume, speed, effects
add_image	Add image assets	image_url, transform, animation, transition
add_subtitle	Add subtitle files	srt_path, font_style, position
add_effect	Add visual effects	effect_type, parameters, duration
add_sticker	Add sticker elements	resource_id, position, scale, rotation
add_video_keyframe	Add keyframe animations	property_types, times, values
get_video_duration	Get video duration	video_url
save_draft	Save draft project	draft_id

Installation & Setup

Requirements

• Python 3.10+
• CapCut Application (macOS/Windows)
• MCP Client Support

Dependencies Installation

# Create virtual environment
python3.10 -m venv venv-mcp
source venv-mcp/bin/activate  # macOS/Linux
# or venv-mcp\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements-mcp.txt

MCP Configuration

Create or update mcp_config.json file:

{
  "mcpServers": {
    "capcut-api": {
      "command": "python3.10",
      "args": ["mcp_server.py"],
      "cwd": "/path/to/CapCutAPI-dev",
      "env": {
        "PYTHONPATH": "/path/to/CapCutAPI-dev"
      }
    }
  }
}

Usage Guide

Basic Workflow

1. Create Draft

# Create 1080x1920 portrait project
result = mcp_client.call_tool("create_draft", {
    "width": 1080,
    "height": 1920
})
draft_id = result["draft_id"]

2. Add Content

# Add title text
mcp_client.call_tool("add_text", {
    "text": "My Video Title",
    "start": 0,
    "end": 5,
    "draft_id": draft_id,
    "font_size": 48,
    "font_color": "#FFFFFF"
})

# Add background video
mcp_client.call_tool("add_video", {
    "video_url": "https://example.com/video.mp4",
    "draft_id": draft_id,
    "start": 0,
    "end": 10,
    "volume": 0.8
})

3. Save Project

# Save draft
result = mcp_client.call_tool("save_draft", {
    "draft_id": draft_id
})

Advanced Features

Text Styling

# Text with shadow and background
mcp_client.call_tool("add_text", {
    "text": "Advanced Text Effects",
    "draft_id": draft_id,
    "font_size": 56,
    "font_color": "#FFD700",
    "shadow_enabled": True,
    "shadow_color": "#000000",
    "shadow_alpha": 0.8,
    "background_color": "#1E1E1E",
    "background_alpha": 0.7,
    "background_round_radius": 15
})

Keyframe Animation

# Scale and opacity animation
mcp_client.call_tool("add_video_keyframe", {
    "draft_id": draft_id,
    "track_name": "video_main",
    "property_types": ["scale_x", "scale_y", "alpha"],
    "times": [0, 2, 4],
    "values": ["1.0", "1.5", "0.5"]
})

Multi-Style Text

# Different colored text segments
mcp_client.call_tool("add_text", {
    "text": "Colorful Text Effect",
    "draft_id": draft_id,
    "text_styles": [
        {"start": 0, "end": 2, "font_color": "#FF0000"},
        {"start": 2, "end": 4, "font_color": "#00FF00"}
    ]
})

Testing & Validation

Using Test Client

# Run test client
python test_mcp_client.py

Functionality Checklist

• Server starts successfully
• Tool list retrieval works
• Draft creation functionality
• Text addition functionality
• Video/audio/image addition
• Effects and animation functionality
• Draft saving functionality

Troubleshooting

Common Issues

1. "CapCut modules not available"

Solution:

• Confirm CapCut application is installed
• Check Python path configuration
• Verify dependency package installation

2. Server startup failure

Solution:

• Check virtual environment activation
• Verify configuration file paths
• Review error logs

3. Tool call errors

Solution:

• Check parameter format
• Verify media file URLs
• Confirm time range settings

Debug Mode

# Enable verbose logging
export DEBUG=1
python mcp_server.py

Best Practices

Performance Optimization

1. Media Files: Use compressed formats, avoid oversized files
2. Time Management: Plan element timelines reasonably, avoid overlaps
3. Memory Usage: Save drafts promptly, clean temporary files

Error Handling

1. Parameter Validation: Check required parameters before calling
2. Exception Catching: Handle network and file errors
3. Retry Mechanism: Retry on temporary failures

API Reference

Common Parameters

• draft_id: Unique draft identifier
• start/end: Time range (seconds)
• width/height: Project dimensions
• transform_x/y: Position coordinates
• scale_x/y: Scale ratios

Response Format

{
  "success": true,
  "result": {
    "draft_id": "dfd_cat_xxx",
    "draft_url": "https://..."
  },
  "features_used": {
    "shadow": false,
    "background": false,
    "multi_style": false
  }
}

Changelog

v1.0.0

• Initial release
• Support for 11 core tools
• Complete MCP protocol implementation

Technical Support

For questions or suggestions, please contact us through:

• GitHub Issues
• Technical Documentation
• Community Forums

---

This documentation is continuously updated. Please follow the latest version.