McpCut MCP Server

mcpCut

A real video editor for AI agents, served over MCP.

mcpCut gives any MCP-capable agent (Claude Code, Claude Desktop, or anything else that speaks the protocol) an actual editing model — not a wrapper around one ffmpeg command. Projects are immutable snapshots with a journaled history of named operations; rendering goes through FFmpeg or the MLT framework; a deterministic CLI twin drives the same logic without a server.

Two ways to use it

☁️ Hosted (fastest — no install). mcpcut.com runs this editor as a service, with a browser editor on top: sign up, create an API token, and point your agent at the cloud MCP endpoint:

claude mcp add --transport http mcpcut https://mcpcut.com/mcp \
  --header "Authorization: Bearer <your token>"

You and your agent then work on the same projects — the agent edits over MCP, you review and tweak in the browser editor.

🖥 Self-hosted (this repository). The open, single-user core: run it on your own machine, point your agent at it, keep everything local. No accounts, no browser editor — just the MCP server, the editing engine and the CLI. The rest of this README is about this option.

What the agent gets

44 tools over one consistent model:

• Projects & history — create/list projects, journaled operations (editor_get_history shows every edit ever made), named versions with restore, annotations.
• Timeline — multiple video/audio tracks, clips with trim/split/move/ resize, transforms with keyframes, transitions, canvas fit, color adjustments.
• Text & graphics — text overlays rasterized server-side, image/video overlays, covers.
• Audio — music beds, per-clip audio, volume envelopes.
• Media in — local paths or URLs (URL import goes through an SSRF egress guard; media is sanity-checked with ffprobe before it touches a timeline).
• Understanding — media analysis (scenes, audio peaks, keyframes), auto-captions via faster-whisper (.[asr] extra), local voiceover via piper (.[tts] extra, GPL — see THIRD_PARTY_NOTICES.md).
• Out — validation, preview renders, full exports with presets. Each export writes an .mlt sidecar you can open in Shotcut or Kdenlive.

Every mutation validates its arguments against the tool's real signature (strings can't leak into numeric filter fields), returns a fresh snapshot with a bumped version, and lands in the journal. Nothing edits in place.

Prerequisites

• Python 3.12+
• FFmpeg (ffmpeg + ffprobe on PATH)
• MLT (melt on PATH) — the default render engine. Alternatively set RENDER_ENGINE=ffmpeg and skip melt.
• A font for text rendering, e.g. Debian/Ubuntu: apt install fonts-dejavu-core fonts-noto-color-emoji (elsewhere, point FONT_PATH at any .ttf).

# Debian/Ubuntu, everything at once:
apt install ffmpeg melt fonts-dejavu-core fonts-noto-color-emoji

Quickstart

git clone https://github.com/musyta-labs/mcpCut && cd mcpCut
python3 -m venv .venv && .venv/bin/pip install -e .

cp .env.example .env       # MCP_AUTH_ENABLED=false is already set there
.venv/bin/python -m app.mcp.server

The server starts on http://127.0.0.1:8100 — the MCP endpoint is http://127.0.0.1:8100/mcp. The database (SQLite) and media workspace are created on first run.

Or with Docker (ffmpeg, melt and fonts included in the image):

docker build -t mcpcut .
docker run -p 127.0.0.1:8100:8100 -e MCP_TRANSPORT=streamable-http \
  -v mcpcut-data:/data mcpcut

Single-user by design. This build has no accounts: whoever can reach the port is the operator, with full tool access including local file paths. Keep it bound to localhost, or put an authenticating reverse proxy in front. MCP_AUTH_ENABLED=false must be set explicitly — the server refuses to start otherwise, so an open port is always a decision you made.

Connect an agent

Claude Code:

claude mcp add --transport http mcpcut http://127.0.0.1:8100/mcp

Any other MCP client, in its JSON config:

{
  "mcpServers": {
    "mcpcut": { "type": "http", "url": "http://127.0.0.1:8100/mcp" }
  }
}

Then ask the agent for something real: “make a 30-second cut of ~/videos/talk.mp4 with auto-captions and export it.” The skills/ directory contains ready-made instructions you can hand to any agent — see skills/README.md.

Or drive it without a server

The CLI twin runs the same operations deterministically:

echo '{"op": "create_project", "args": {"metadata": {}}}' > /tmp/ops.json
.venv/bin/python -m app.mcp.cli /tmp/ops.json

Configuration

Everything lives in environment variables (or .env); see .env.example for the full annotated list. The ones that matter most:

Retention is real: a background daemon deletes exports after 24 h and cached clips after 48 h by default. On a personal machine either download your exports promptly or set RETENTION_ENABLED=false.

How it's built

Safety properties the codebase holds everywhere: no shell=True (argv lists only), timeouts on every subprocess, atomic export writes, SSRF egress guard on URL imports, argument validation derived from tool signatures.

License

MIT. Third-party obligations (FFmpeg/MLT installed by you, the GPL piper-tts extra, fonts) are documented in THIRD_PARTY_NOTICES.md.