内容
# 🎬 capcut-mcp
> 服务 **MCP** (模型上下文协议) 服务器，允许像 **Claude** 这样的 AI 助手 **创建 CapCut 视频剪辑**：组装剪辑，添加文本/字幕，音乐，转换，效果……然后直接在 CapCut 中保存项目，准备导出。
---
## 🧠 工作原理（简单来说）
CapCut **没有官方 API** 来远程控制它。但是应用程序将每个项目以 **“草稿”** （draft）的形式存储在您的磁盘上：实际上是描述整个剪辑的 JSON 文本文件（哪些剪辑，在什么时候，什么效果……）。
该服务器使用开源库 [`pyJianYingDraft`](https://github.com/GuanYixuan/pyJianYingDraft) （JianYing 是 CapCut 的原始版本，使用相同的引擎） **为您编写这些草稿文件**。
```
Claude ──(MCP 命令)──► capcut-mcp ──► pyJianYingDraft ──► CapCut 草稿文件在磁盘上
│
您打开 CapCut ▼ 并导出
```
> 📌 **重要**：服务器 **创建和修改剪辑**，但 **不进行最终视频导出**。导出在 CapCut 中手动完成（CapCut 不允许命令行导出）。服务器在与 CapCut **相同的机器上运行**（需要访问您的文件）。
---
## 📦 安装
需要 **Python 3.10+** 和已安装的 **CapCut Desktop** 应用程序。
```bash
# 1. 获取代码
git clone https://github.com/pintoj71/capcut-mcp.git
cd capcut-mcp
# 2. 安装
pip install -e .
```
---
## 🔌 将服务器连接到 Claude
### Claude Desktop / Claude Code
在您的 MCP 配置文件（`claude_desktop_config.json` 用于桌面应用程序，或 `.mcp.json` 用于 Claude Code）中添加以下内容：
```json
{
"mcpServers": {
"capcut": {
"command": "capcut-mcp",
"env": {
"CAPCUT_DRAFT_FOLDER": "C:\\Users\\您的名称\\AppData\\Local\\CapCut\\User Data\\Projects\\com.lveditor.draft"
}
}
}
}
```
> `CAPCUT_DRAFT_FOLDER` 变量指示 CapCut 存储其草稿的位置。如果您省略它，服务器将尝试自动猜测（见下文）。您也可以使用 `set_draft_folder` 工具热定义它。
**草稿文件夹的常用位置：**
| 系统 | 路径 |
|---|---|
| **Windows** | `%LOCALAPPDATA%\CapCut\User Data\Projects\com.lveditor.draft` |
| **macOS** | `~/Movies/CapCut/User Data/Projects/com.lveditor.draft` |
---
## 🎯 从您的捕获 + 照片到 Meta 视频（主要用例）
要发布到 **Instagram / Facebook（短视频，故事，Feed）**，有两个工具完成了大部分工作：
1. **`create_project(name, preset=...)`** — 选择一个 Meta 格式，大小为您设置：
| preset | 大小 | 用途 |
|---|---|---|
| `reels` / `story` / `vertical` | 1080×1920 | 短视频和故事（全屏移动） |
| `feed` / `portrait` | 1080×1350 | Instagram Feed（推荐） |
| `square` | 1080×1080 | 正方形 |
| `landscape` | 1920×1080 | 16:9 风景 |
2. **`add_media_sequence([...])`** — 提供 **您的视频和照片列表**，按所需顺序排列：它们自动连接（无需计算时间）。选项：`transition` 每个媒体之间，`fit="blur"`（模糊背景以适应垂直短视频），`ken_burns=True`（照片轻微缩放），`photo_duration`.
3. **`set_background_music(...)`** — 添加音乐，**整个视频时长**（如果太短则循环播放），带有淡出效果。
### 示例 - 用自然语言向 Claude 发出请求
> “创建一个名为 *construction* 的 **短视频** 项目。将我的捕获和照片从文件夹连接起来：`intro.mp4`，`photo1.jpg`，`photo2.jpg`，`final.mp4`，每个之间 **淡入淡出**，**模糊背景** 和 **轻微缩放** 照片。在前 3 秒钟内在底部添加标题“INSTANT BY PINTO”。添加背景音乐 `fond.mp3`。保存。”
Claude 将连接：`create_project(preset="reels")` → `add_media_sequence([...], transition="叠化", fit="blur", ken_burns=True)` → `add_text(...)` → `set_background_music(...)` → `save_project()`。您打开 CapCut，您的短视频已组装好，准备导出和发布到 Meta。
---
## 💬 使用 Claude 的示例
连接后，只需用自然语言简单请求：
> “创建一个名为 *promo* 的垂直 1080×1920 项目。在开头放置剪辑 `C:\videos\intro.mp4`，然后放置剪辑 `C:\videos\produit.mp4`，并使用淡入淡出过渡。添加标题“PROMO -50%”在前 3 秒钟内，并在中心以大字体显示。添加音乐 `C:\audio\fond.mp3` 作为背景，音量为 30%。保存。”
Claude 将连接工具：`create_project` → `add_video_clip` ×2 → `add_text` → `add_audio` → `save_project()`。然后，您打开 CapCut，项目 *promo* 已准备好导出。
---
## 🧰 可用工具
### 配置和项目
| 工具 | 角色 |
|---|---|
| `get_status` | 状态：草稿文件夹，活动项目 |
| `set_draft_folder` | 定义 CapCut 草稿文件夹 |
| `create_project` | 创建项目（Meta 短视频/Feed/正方形... 或大小，帧率） |
| `set_active_project` | 切换到另一个打开的项目 |
| `add_track` | 添加轨道（叠加层） |
### 媒体
| 工具 | 角色 |
|---|---|
| ⭐ `add_media_sequence` | **自动连接** 视频和照片列表（过渡，模糊背景，缩放） |
| ⭐ `set_background_music` | 背景音乐，整个视频时长（循环播放 + 淡出） |
| `add_video_clip` | 添加精确的视频剪辑（速度，音量，位置，过渡，动画，滤镜，效果...） |
| `add_image` | 添加静态图像（幻灯片） |
| `add_audio` | 在特定时刻添加音频/旁白 |
| `inspect_media` | 读取文件时长/尺寸 |
### 文本
| 工具 | 角色 |
|---|---|
| `add_text` | 标题/字幕（字体，颜色，轮廓，背景，动画） |
| `add_subtitles_from_srt` | 导入 `.srt` 字幕文件 |
### 效果和滤镜（完整时间线）
| 工具 | 角色 |
|---|---|
| `add_effect` | 在时间范围内添加视觉效果 |
| `add_filter` | 在时间范围内添加颜色滤镜 |
### 保存和发现
| 工具 | 角色 |
|---|---|
| `save_project` | 将草稿写入磁盘 |
| `list_projects` | 列出存在的草稿 |
| `search_transitions` / `search_filters` / `search_video_effects` / `search_video_animations` / `search_text_animations` / `search_audio_effects` / `search_fonts` | 查找有效的效果/过渡/字体名称 |
> 🔎 CapCut 的效果/过渡名称通常为 **中文**（引擎为中文）。`search_*` 工具帮助您找到正确的名称。`add_*` 同时接受原始中文名称和英文名称（如果存在）。
---
## ⏱️ 约定
- **所有时间均为秒** (`start`, `duration`, `fade_in`...).
- **颜色为十六进制**：`#FFFFFF` （白色），`#FF0000` （红色）...
- **屏幕位置**：`position_x` / `position_y` 介于 `-1` 和 `1` 之间，`0` = 居中。`position_y = -0.8` ≈ 屏幕底部（字幕）。
- **轨道**：每种类型（视频，音频，文本...）都有一个自动创建的主轨道。对于 **叠加层** （第二个剪辑在第一个剪辑上，第二个文本...），请传递命名轨道或使用 `add_track` 创建。
---
## ⚠️ 已知限制
- **没有自动导出**：CapCut 不允许命令行导出；我们生成项目，手动导出在 CapCut 中完成。
- **草稿格式 ≈ CapCut 版本**：`pyJianYingDraft` 针对 CapCut/JianYing 的某些版本。如果生成的项目无法打开，请检查库版本兼容性。
- **文件路径**：使用 **绝对路径** 访问媒体文件；服务器在与 CapCut **相同的机器上运行**。
- 项目 **非 CapCut/ByteDance 官方**。个人使用。
---
## 📄 许可证
MIT — 请参阅 [LICENSE](LICENSE).
基于 [`pyJianYingDraft`](https://github.com/GuanYixuan/pyJianYingDraft) （草稿生成引擎）和 [`mcp`](https://github.com/modelcontextprotocol/python-sdk) SDK。
