CapCutAPI/README.md

CapCutAPI

Open source CapCut API tool with MCP (Model Context Protocol) support.

Try It: https://www.capcutapi.top

中文说明 | MCP Documentation | MCP 中文文档

🎬 Gallery

Connect AI generated via CapCutAPI

🚀 Project Features

This project is a Python-based CapCut processing tool that offers comprehensive video editing capabilities through multiple interfaces:

🎯 Core Features

• Draft File Management: Create, read, modify, and save CapCut draft files
• Material Processing: Support adding and editing various materials such as videos, audios, images, texts, stickers, etc.
• Effect Application: Support adding multiple effects like transitions, filters, masks, animations, etc.
• API Service: Provide HTTP API interfaces to support remote calls and automated processing
• AI Integration: Integrate multiple AI services to support intelligent generation of subtitles, texts, and images
• 🆕 MCP Support: Model Context Protocol integration for seamless AI assistant integration

📡 Available Interfaces

HTTP API Endpoints

• /create_draft: Create a draft
• /add_video: Add video material to the draft
• /add_audio: Add audio material to the draft
• /add_image: Add image material to the draft
• /add_text: Add text material to the draft
• /add_subtitle: Add subtitles to the draft
• /add_effect: Add effects to materials
• /add_sticker: Add stickers to the draft
• /save_draft: Save the draft file

🆕 MCP Tools (11 Tools Available)

• create_draft: Create new video draft project
• add_video: Add video track with transitions and effects
• add_audio: Add audio track with volume control
• add_image: Add image assets with animations
• add_text: Add text with shadows, backgrounds, and multi-styles
• add_subtitle: Add SRT subtitles with styling
• add_effect: Add visual effects
• add_sticker: Add sticker elements
• add_video_keyframe: Add keyframe animations
• get_video_duration: Get video duration
• save_draft: Save draft project

🛠️ Installation & Setup

Prerequisites

ffmpeg

This project depends on ffmpeg. Ensure ffmpeg is installed and added to your system's PATH.

Python Environment

Requires Python 3.8.20 or higher. Ensure the correct Python version is installed.

Installation Steps

1. Clone the repository

git clone https://github.com/sun-guannan/CapCutAPI.git
cd CapCutAPI

2. Install dependencies

# For HTTP API server
pip install -r requirements.txt

# For MCP server (additional)
pip install -r requirements-mcp.txt

3. Configuration

cp config.json.example config.json
# Edit config.json as needed

🚀 Usage

HTTP API Server

Start the HTTP API server:

python capcut_server.py

🆕 MCP Server

The MCP server provides seamless integration with AI assistants and other MCP-compatible clients.

Quick Start

1. Start MCP Server

python mcp_server.py

2. Configure MCP Client Create or update your mcp_config.json:

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

3. Test MCP Connection

python test_mcp_client.py

MCP Features

• 🎨 Advanced Text Styling: Multi-color text, shadows, backgrounds
• 🎬 Video Processing: Keyframe animations, transitions, effects
• 🔊 Audio Control: Volume adjustment, speed control
• 📱 Multi-format Support: Various video dimensions and formats
• ⚡ Real-time Processing: Immediate draft updates and previews

📖 Usage Examples

HTTP API Examples

Adding a Video

import requests

response = requests.post("http://localhost:9001/add_video", json={
    "video_url": "http://example.com/video.mp4",
    "start": 0,
    "end": 10,
    "width": 1080,
    "height": 1920
})

print(response.json())

Adding Text

import requests

response = requests.post("http://localhost:9001/add_text", json={
    "text": "Hello, World!",
    "start": 0,
    "end": 3,
    "font": "ZY_Courage",
    "font_color": "#FF0000",
    "font_size": 30.0
})

print(response.json())

Saving a Draft

import requests

response = requests.post("http://localhost:9001/save_draft", json={
    "draft_id": "123456",
    "draft_folder": "your capcut draft folder"
})

print(response.json())

🆕 MCP Usage Examples

Basic Workflow

# Create a new draft
draft = mcp_client.call_tool("create_draft", {
    "width": 1080,
    "height": 1920
})

# Add text with advanced styling
mcp_client.call_tool("add_text", {
    "text": "Welcome to CapCut!",
    "start": 0,
    "end": 5,
    "draft_id": draft["draft_id"],
    "font_size": 48,
    "shadow_enabled": True,
    "background_color": "#000000"
})

# Save the project
mcp_client.call_tool("save_draft", {
    "draft_id": draft["draft_id"]
})

Advanced Features

# Add video with keyframe animation
mcp_client.call_tool("add_video_keyframe", {
    "draft_id": draft_id,
    "track_name": "main_video",
    "property_types": ["scale_x", "scale_y", "alpha"],
    "times": [0, 2, 4],
    "values": ["1.0", "1.5", "0.8"]
})

Testing with REST Client

You can use the rest_client_test.http file with REST Client IDE plugins for HTTP testing.

Draft Management

Calling save_draft generates a folder starting with dfd_ in the server's current directory. Copy this folder to your CapCut draft directory to access the generated draft in CapCut.

📚 Documentation

• MCP English Documentation: Complete MCP server usage guide
• MCP 中文文档: 完整的 MCP 服务器使用指南
• API Reference: More usage examples including audio and effects

🌟 Project Highlights

• 🌍 Cross-platform Support: Supports both CapCut China version and CapCut International version
• 🤖 Automated Processing: Supports batch processing and automated workflows
• 🔌 Rich APIs: Provides comprehensive API interfaces for easy integration
• ⚙️ Flexible Configuration: Achieve flexible function customization through configuration files
• 🧠 AI Enhancement: Integrate multiple AI services to improve video production efficiency
• 🆕 MCP Integration: Seamless integration with AI assistants and automation tools

🔧 Advanced Configuration

MCP Server Configuration

For production use, you can configure the MCP server with additional options:

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

Environment Variables

• DEBUG: Enable debug logging
• CAPCUT_PATH: Custom CapCut installation path
• DRAFT_OUTPUT_PATH: Custom draft output directory

🤝 Contributing

We welcome contributions! Please feel free to submit issues and pull requests.

📈 Star History

📄 License

This project is open source. Please check the license file for details.

---

🎉 New: Now with MCP support for seamless AI assistant integration! Try the MCP server for advanced video editing automation.