内容
# 🎬 CapCut MCP 服务器
一款给予 AI 助手对 CapCut 视频编辑项目完全控制权的 **MCP（模型上下文协议）服务器**。创建项目、导入媒体、添加文本/字幕、管理音频和编辑时间线 — 所有这些都可以通过 AI 驱动的工具完成。
## 工作原理
```text
AI 助手 ──MCP 协议──▶ CapCut MCP 服务器 ──读写 JSON──▶ CapCut 草稿文件
(Python/FastMCP) (draft_content.json)
```
CapCut 将每个项目存储为一个文件夹，包含一个 `draft_content.json` 文件。MCP 服务器直接读取和写入这些文件。你可以通过 AI 编辑项目，然后在 CapCut 中打开项目进行预览和导出。
## 快速入门
### 1. 安装
```bash
# 克隆您的仓库
git clone https://github.com/baizo7/capcut_MCP_server-.git
cd capcut_MCP_server-
# 使用 pip
pip install -e ".[cli]"
# 或使用 uv（推荐）
uv pip install -e .
```
### 2. 配置您的 MCP 客户端
#### Gemini IDE / Antigravity
在 Windows 上，打开位于 `%USERPROFILE%\.gemini\config\mcp_config.json` 的 Gemini MCP 配置文件。
在 `mcpServers` 对象中添加以下内容：
```json
{
"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"
}
}
}
}
```
*注意：保存后，重启 IDE 以启动新的服务器。*
#### Claude Desktop
在 `claude_desktop_config.json` 中添加以下内容：
```json
{
"mcpServers": {
"capcut": {
"command": "python",
"args": ["-m", "capcut_mcp.server"]
}
}
}
```
#### Cursor IDE
在项目中的 `.cursor/mcp.json` 中添加以下内容：
```json
{
"mcpServers": {
"capcut": {
"command": "python",
"args": ["-m", "capcut_mcp.server"]
}
}
}
```
### 3. 开始编辑！
配置完成后，您的 AI 助手可以使用以下命令：
- *"创建一个名为 'Summer Vibes' 的新 TikTok 项目"*
- *"导入 D:\footage\vacation 中的所有视频并将它们添加到时间线"*
- *"添加字幕：'Hello!' 在 0-2s 和 'Welcome!' 在 2-5s"*
- *"将第一个片段修剪到 3 秒开始"*
---
## 🛑 重要限制和解决方法
### 1. Windows Store Python 沙盒
如果您使用从 **Microsoft Store** 安装的 Python 运行 MCP 服务器（在 Gemini IDE 和 Cursor 中很常见），Windows 会自动将写入 `AppData\Local` 的操作沙盒化。
* **问题：** AI 将完美地创建项目，但 Windows 会将它们隐藏在 CapCut 中。
* **解决方法：** 我们在服务器中内置了使用 PowerShell 的自动 "沙盒逃脱" 功能！但是，为了获得最佳结果，我们强烈建议将 CapCut 的默认保存位置（设置 -> 项目 -> 保存到）更改为您的 `Documents` 文件夹，并更新您的 `CAPCUT_DRAFTS_PATH` 环境变量以匹配它。
### 2. CapCut 不会 "热重载"
由于我们是在 CapCut 的背后编辑硬盘上的原始 JSON 保存文件，CapCut 不会在您积极编辑时间线时立即更新其屏幕。
* **查看更改：** 您必须单击 CapCut 中的 "X" 返回主页，然后再次单击项目，以强制 CapCut 从硬盘重新加载时间线。
* **对于新项目：** 只需切换标签页（例如，从 "Space" 到 "Home"）以刷新项目列表。
---
## 配置
| 环境变量 | 描述 | 默认值 |
|---|---|---|
| `CAPCUT_DRAFTS_PATH` | CapCut 草稿文件夹的路径 | 自动发现 |
### 自动发现
服务器会自动检查以下位置是否存在 CapCut 项目：
- `%LOCALAPPDATA%\CapCut\User Data\Projects\com.lveditor.draft`
- `%LOCALAPPDATA%\CapCut\User Data\Drafts`
---
## 可用工具（25+）
### 📁 项目管理
| 工具 | 描述 |
|---|---|
| `list_projects` | 列出此计算机上的所有 CapCut 项目 |
| `get_project_info` | 详细的项目信息：音轨、素材、片段 |
| `create_project` | 创建一个新空项目（带有画布预设） |
| `duplicate_project` | 克隆项目作为模板 |
| `delete_project` | 删除项目（需要确认） |
| `list_canvas_presets` | 显示可用的画布尺寸（横向、纵向等） |
### 🎥 媒体导入
| 工具 | 描述 |
|---|---|
| `add_video` | 将视频文件导入时间线 |
| `add_image` | 添加图像作为静态片段 |
| `add_media_batch` | 从文件夹批量导入所有媒体 |
| `list_materials` | 列出项目中的所有资产 |
| `remove_material` | 删除资产及其时间线片段 |
### 📝 文本和字幕
| 工具 | 描述 |
|---|---|
| `add_text` | 在特定时间添加文本叠加层 |
| `add_subtitles` | 从结构化列表批量添加字幕 |
| `update_text_style` | 更改字体、颜色、大小、对齐方式 |
| `update_text_content` | 更改文本内容 |
### 🔊 音频
| 工具 | 描述 |
|---|---|
| `add_audio` | 添加背景音乐或音效 |
| `set_volume` | 调整特定片段的音量 |
| `mute_track` | 静音音轨上的所有片段 |
| `unmute_track` | 恢复静音音轨的音量 |
### ✂️ 时间线编辑
| 工具 | 描述 |
|---|---|
| `trim_clip` | 修剪片段的开始/结束点 |
| `split_clip` | 在时间戳处将片段分成两部分 |
| `move_clip` | 将片段移动到新的时间线位置 |
| `delete_clip` | 从时间线中删除片段 |
| `reorder_clips` | 以可选的间隔顺序排列片段 |
| `set_clip_speed` | 更改播放速度（慢动作、快进） |
---
## 安全功能
- **自动备份：** 每次编辑都会在修改前创建 `.backup` 备份。
- **非破坏性：** 删除操作需要明确确认。
- **验证：** 所有文件路径在导入前都会被验证。
---
## 开发
```bash
# 以开发模式安装
pip install -e ".[dev]"
# 运行测试
python -m pytest tests/ -v
# 使用 MCP Inspector（基于浏览器）进行测试
npx -y @modelcontextprotocol/inspector python -m capcut_mcp.server
```
---
## 重要注意事项
⚠️ **非官方：** 该服务器反向工程 CapCut 的项目格式。它与 ByteDance 无关联。
⚠️ **备份：** 服务器在修改前会自动备份项目，但请始终保留重要项目的备份。
⚠️ **ffprobe：** 为了准确检测视频/音频时长，请安装 [FFmpeg](https://ffmpeg.org/download.html) 并确保 `ffprobe` 在您的 PATH 中。否则，服务器将使用默认时长估计。
