# video-editor-mcp

An MCP (Model Context Protocol) server that gives Claude a full conversational video-editing toolkit — trim, crop, color grade, caption, beat-sync, stabilize, and more — built on `ffmpeg`, `faster-whisper`, and `yt-dlp`, with optional DaVinci Resolve and CapCut integration.

Describe the edit you want in chat; Claude calls the tools to do it.

## Tools

| Category | Tools |
|---|---|
| Download | `download_video` — from YouTube, Instagram, TikTok, Facebook, Vimeo, or any direct link (1000+ sites via yt-dlp) |
| Analysis | `get_video_info`, `detect_scenes`, `analyze_style` — probe a file or reverse-engineer a reference reel's cut pace, color mood, and orientation |
| Basic editing | `trim_video`, `merge_videos`, `extract_audio`, `change_speed`, `add_audio` |
| Visual | `color_grade` (cinematic/bright/moody/vibrant/bw/vintage presets), `add_text_overlay`, `crop_and_resize` (9:16/1:1/16:9/4:5), `stabilize_video` |
| AI | `auto_captions` — Whisper-based, burns in or exports `.srt`, multi-language |
| Smart editing | `edit_like_reference` — analyzes a reference reel's pace/color/orientation and re-cuts your footage to match, `beat_sync_edit` — cuts footage on detected music beats, `auto_best_moments` — extracts a highlight reel from long raw footage |
| Batch | `batch_process` — run one operation across every video in a folder |
| Sharing | `share_file` — upload a result and get a shareable link (gofile/transfer.sh) |
| DaVinci Resolve (optional) | `davinci_status`, `davinci_create_timeline` — only active if Resolve is installed |
| CapCut (optional) | `list_capcut_drafts`, `launch_capcut` — only active if CapCut is installed |

## Setup

**1. Clone and install Python deps**

```bash
git clone https://github.com/dr-ashraf-s-MCP-LABS/video-editor-mcp.git
cd video-editor-mcp
pip install -r requirements.txt
```

You'll also need `ffmpeg` on your PATH (or `imageio-ffmpeg`, which the server falls back to automatically) and `yt-dlp`.

**2. Configure (optional)**

Copy `.env.example` to `.env` and adjust if you need non-default binary locations, want to point at your own CapCut/DaVinci install, or need a `cookies.txt` for Instagram/Facebook downloads (export one with a browser extension like "Get cookies.txt LOCALLY").

**3. Register with Claude**

Add to your Claude Desktop / Claude Code MCP config:

```json
{
  "mcpServers": {
    "video-editor": {
      "command": "python",
      "args": ["/absolute/path/to/video-editor-mcp/server.py"]
    }
  }
}
```

Restart Claude and start editing conversationally, e.g.: *"Download this reel, match its style to my raw footage, add this music, and caption it."*

## Notes

- `download_video`, `output`, and downloaded files land in `./downloads` and `./output` next to `server.py` by default — override with `VIDEO_EDITOR_DOWNLOADS_DIR` / `VIDEO_EDITOR_OUTPUT_DIR`.
- CapCut and DaVinci Resolve tools degrade gracefully (report "not installed") if you haven't set the relevant env vars or don't have those apps.
- `auto_captions` and `batch_process`'s captions mode download the Whisper `base` model (~150MB) on first use.

## License

MIT — see [LICENSE](LICENSE).