free-video-edit-mcp

Free, open-source MCP server for programmatic video editing via FFmpeg/ffprobe.

Gives AI agents deterministic, verifiable edit tools without DaVinci Resolve or any paid NLE. Structured edits, a powerful argv escape hatch, live docs for your installed FFmpeg build, simple LUT helpers, and plan-vs-output verification over the Model Context Protocol.

Not affiliated with Blackmagic Design. This project does not reverse engineer Resolve, touch Resolve binaries, or implement proprietary Resolve APIs. It is a clean-room FFmpeg workflow exposed as an MCP server (MIT).

Features

• 16 tools for probe, trim, concat, timeline compose, markers, LUT generate/apply, render presets, docs search, and verify

• Dual transport: stdio (Cursor / Claude Desktop) and streamable HTTP (ChatGPT remote connectors)

• Deterministic JSON results (paths, durations, exit codes, stderr tails)

• Safety guards on run_ffmpeg (argv only, workspace path checks)

Related MCP server: ffmpeg-mcp

Requirements

• Python 3.10+

• FFmpeg + ffprobe on PATH (tested with FFmpeg 7.x)

• An MCP host: Cursor, Claude Desktop, or ChatGPT (remote HTTP)

Install from clone

git clone https://github.com/breverdbidder/free-video-edit-mcp.git
cd free-video-edit-mcp
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\\Scripts\\activate
pip install -e ".[dev]"

Set a media workspace (optional; defaults to ~/video-projects):

export FREE_VIDEO_EDIT_ROOT="$HOME/video-projects"
mkdir -p "$FREE_VIDEO_EDIT_ROOT"

Run

Stdio (default Cursor / Claude Desktop)

python -m free_video_edit_mcp
# or after install:
free-video-edit-mcp

Streamable HTTP (ChatGPT / remote)

python -m free_video_edit_mcp --transport streamable-http --host 127.0.0.1 --port 8765
# alias for the same transport:
python -m free_video_edit_mcp --transport http --host 127.0.0.1 --port 8765

MCP endpoint (local): http://127.0.0.1:8765/mcp

Legacy SSE is also available via --transport sse (prefer streamable-http for new remote clients).

Cursor

1. Install the package (see above).

2. Open Cursor MCP settings and merge the server block (or copy from configs/cursor.mcp.json).

Exact JSON (adjust the Python path if you use a venv):

{
  "mcpServers": {
    "free-video-edit": {
      "command": "/absolute/path/to/free-video-edit-mcp/.venv/bin/python",
      "args": ["-m", "free_video_edit_mcp"],
      "env": {
        "FREE_VIDEO_EDIT_ROOT": "/absolute/path/to/your/video-projects"
      }
    }
  }
}

On Windows, use the venv interpreter, for example:

C:\\path\\to\\free-video-edit-mcp\\.venv\\Scripts\\python.exe

Restart Cursor (or reload MCP servers) after saving.

Claude Desktop

1. Install the package.

2. Edit Claude Desktop’s config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\\Claude\\claude_desktop_config.json

3. Merge the server block (also in configs/claude_desktop.mcp.json):

{
  "mcpServers": {
    "free-video-edit": {
      "command": "/absolute/path/to/free-video-edit-mcp/.venv/bin/python",
      "args": ["-m", "free_video_edit_mcp"],
      "env": {
        "FREE_VIDEO_EDIT_ROOT": "/absolute/path/to/your/video-projects"
      }
    }
  }
}

Fully quit and reopen Claude Desktop so it picks up the config.

ChatGPT (remote / streamable HTTP)

ChatGPT does not use local stdio MCP. It expects a remote MCP connector pointing at a URL your machine (or host) serves — almost always a public HTTPS URL.

Steps

1. Start the HTTP transport locally:

python -m free_video_edit_mcp --transport http --host 127.0.0.1 --port 8765

2. Expose it with a tunnel (examples):

# Cloudflare Tunnel
cloudflared tunnel --url http://127.0.0.1:8765

# or ngrok
ngrok http 8765

3. In ChatGPT → Settings → Connectors / Advanced → MCP (labels vary by plan), add a remote MCP server URL such as:

https://YOUR-TUNNEL-HOST/mcp

4. Enable the connector in a tools-capable chat.

Full notes: configs/chatgpt.remote.md.

Caveats

• Public HTTPS is typically required; http://127.0.0.1:8765/mcp alone will not work for ChatGPT.

• A public tunnel exposes FFmpeg tools on your machine. Use auth, IP allowlists, or a private deployment; do not leave an open tunnel unattended.

• ChatGPT MCP / connector UI availability depends on your OpenAI plan and product surface. If you cannot add a remote MCP connector, use Cursor or Claude Desktop with stdio instead.

Tool list (16)

Limitations vs DaVinci Resolve

If you need a full NLE, use Resolve (or another editor). If you need an agent to trim, concat, grade lightly, export, and verify on a headless box, use this.

Safety notes for run_ffmpeg

• Never pass a shell string; always an argv list[str].

• Default workspace guard: paths outside FREE_VIDEO_EDIT_ROOT are rejected unless allow_any_path=true.

• Overwrite only when overwrite=true (passes -y); otherwise -n.

• Prefer structured tools (trim_clip, concat_clips, …) so results stay verifiable.

• On remote/HTTP deployments, treat tool access as equivalent to running FFmpeg as the server user.

Example agent prompts

• “Probe interview.mp4, trim the intro to the first 5 seconds, concat with broll.mp4, then verify_edit for ~duration and 1280×720.”

• “Generate a slight warm LUT (temperature +20, saturation 1.1), apply it to hero.mp4, export h264_mp4.”

• “Search FFmpeg docs for lut3d and show me the filter help for the installed build.”

• “Compose this timeline JSON and verify the output is between 12 and 16 seconds.”

Sample plan: examples/sample_edit_plan.json.

Development / pytest

source .venv/bin/activate
pip install -e ".[dev]"
pytest -q

Smoke tests synthesize tiny color-bars + sine clips with FFmpeg, then trim, concat, LUT, render, and verify.

Project layout

configs/                 # Cursor, Claude Desktop, ChatGPT connector helpers
examples/                # Sample MCP config + edit plan
src/free_video_edit_mcp/ # Server + FFmpeg helpers
tests/                   # Smoke tests

License

MIT — see LICENSE.