Skip to content
v1.4.0 — 119 guardrailed tools tested & working

# 119 Guardrailed Video Tools.
Zero Cloud Costs.

Local video processing for AI agents. An open-source MCP server that gives Claude Code, Cursor, and any AI agent 119 video editing tools via FFmpeg and Hyperframes, with guardrails for filters, merges, overlays, text, layout, and audio. Fast, free, and 100% private.

119
Tools
1215
Tests
279
Commits
$0
Forever
View on GitHub pip install mcp-video
mcp-video
$ mcp-video trim input.mp4 -s 0:30 -d 15 -o clip.mp4
✓ clip.mp4 — 15.0s @ 1920x1080
$ mcp-video filter clip.mp4 -t grayscale -o bw.mp4
✓ bw.mp4 — grayscale applied
$ mcp-video add-text bw.mp4 "Hello World" -p center --size 48 -o final.mp4
✓ final.mp4 — text rendered
# Or use the Python client
$ python3 -c 'from mcp_video import Client; c=Client(); c.trim("in.mp4", start=5, duration=10)'
✓ Trimmed to 10s — output: trimmed.mp4
Features
Everything you need to edit video with AI.

119 registered tools across video, audio, effects, AI, Hyperframes, and repurposing workflows. Every tool returns structured JSON with output paths, duration, and resolution. High-risk edit paths now warn or fail early when inputs would silently produce bad output.

10
Core Editing
8
Filters
5
Effects
7
Audio
10
AI Features
8
Hyperframes
✂️

### Core Editing

Trim, merge, crop, rotate, resize, convert, speed change, fade, watermark. The basics, with compatibility guardrails.

10 tools
🎨

### Filters & Effects

Blur, sharpen, grayscale, sepia, vignette, chromatic aberration, scanlines, noise, glow — with bounded filter parameters.

13 tools
🎬

### Transitions

Glitch, pixelate, and morph transitions for seamless clip connections.

3 tools
🎵

### Audio Suite

Normalize, reverb, compress, pitch shift, noise reduction. Mix and generate audio with volume/timing warnings.

7 tools
🤖

### AI-Powered

Whisper transcription, scene detection, stem separation, AI upscaling, color grading, spatial audio.

10 tools
📐

### Layout & MoGraph

Grid layouts, picture-in-picture, split-screen, animated text, count animations, progress bars with layout/timing warnings.

8 tools
Why mcp-video
Not just another FFmpeg wrapper.

Raw FFmpeg is powerful but painful. Cloud APIs are easy but expensive. mcp-video gives you the power of FFmpeg with the ergonomics of a modern API.

| mcp-video | Raw FFmpeg | Cloud APIs
--- | --- | --- | ---
Cost | ✓ Free, local | ✓ Free | ✗ $0.28–$2.50 per 5s
Privacy | ✓ 100% local | ✓ 100% local | ✗ Uploads to cloud
Error handling | ✓ Structured + auto-fix | ✗ Cryptic stderr | ✗ HTTP errors
Validation | ✓ Before execution | ✗ Runtime only | ✓ API schema
Text overlay | `add_text("Hi")` | `-vf "drawtext=text='Hi':fontfile=..."` | Varies
Agent discovery | ✓ 119 self-documenting tools | ✗ Memorize flags | ✗ Read docs
Testing | ✓ 1215 passing tests | ✗ None | Provider's

Tools
119 tools. Every operation you need.

All tested end-to-end on real MP4s. Every tool returns structured JSON with output paths, duration, and resolution.

✓
video_info
Duration, resolution, codec, fps, bitrate
✓
video_trim
Trim by start/duration or end time
✓
video_merge
Concatenate clips with transitions
✓
video_add_text
Overlay text with positioning
✓
video_add_audio
Mix, replace, or add audio tracks
✓
video_resize
Change resolution or aspect ratio
✓
video_convert
mp4, webm, gif, mov with presets
✓
video_speed
Speed up or slow down
✓
video_filter
blur, grayscale, sepia, sharpen, etc.
✓
video_crop / rotate
Crop regions, rotate, flip
✓
video_fade / watermark
Fade in/out, image watermarks
✓
video_subtitles
Burn SRT/VTT, generate from text
✓
video_thumbnail / preview
Extract frames, low-res preview
✓
video_storyboard
Key frame grid for review
✓
video_stabilize
Motion vector stabilization
✓
video_overlay / split_screen
PIP, side-by-side layouts
✓
video_detect_scenes
Auto scene change detection
✓
video_layout_grid / pip
Multi-video grid layouts
✓
video_text_animated
Animated text overlays
✓
video_mograph_count / progress
Counter animations, progress bars
✓
audio_preset / sequence
Synthesized sound effects
✓
audio_compose / effects
Layer tracks, apply reverb, etc.
✓
video_audio_spatial
3D audio positioning
✓
video_ai_transcribe
Whisper speech-to-text
✓
video_ai_stem_separation
Isolate vocals, drums, bass
✓
video_ai_upscale
ML super-resolution (2x/4x)
✓
video_ai_scene_detect
ML scene boundary detection
✓
video_ai_color_grade
Auto color correction
✓
video_ai_remove_silence
Auto-remove dead air
✓
hyperframes_render / still
HTML-native video rendering
✓
search_tools
Search tools by keyword
✓
...and 49 more
See GitHub for full list
Three Interfaces
However you want to use it.

MCP server for AI agents. Python library for scripts. CLI for the terminal. All three share the same guardrailed editing engine.

### MCP Server

Add to Claude Code or Cursor. Then just talk to your agent.

JSON

    {
      "mcpServers": {
        "mcp-video": {
          "command": "uvx",
          "args": ["mcp-video"]
        }
      }
    }

### Python Client

Clean API for automation and pipelines.

Python

    from mcp_video import Client

    editor = Client()
    clip = editor.trim("v.mp4", start="0:30", duration="15")
    final = editor.resize(clip.output_path, aspect_ratio="9:16")
    result = editor.export(final.output_path)
    print(result.resolution)  # 1080x1920

### CLI Tool

Human-friendly terminal output. Add `--format json` for scripting.

Bash

    # Info with rich table output
    $ mcp-video info video.mp4

    # Trim with progress
    $ mcp-video trim video.mp4 -s 0:30 -d 15

    # Apply TikTok template
    $ mcp-video template tiktok video.mp4 --caption "Hello!"

    # JSON output for scripts
    $ mcp-video --format json info video.mp4

Install
Get started in 30 seconds.

Requires Python 3.11+ and FFmpeg installed. AI features need optional dependencies.

Base Install
Terminal

    pip install mcp-video

With AI Features
Terminal

    pip install mcp-video[ai]

Verify Installation
Terminal

    mcp-video --version
    mcp-video doctor  # Check FFmpeg and optional deps

Quality
1215 passing tests. Real media where it matters.

Core video paths use actual FFmpeg operations. Every tool was tested end-to-end on real MP4s.

1215
Passing Tests
119
Registered Tools
7
Guardrail Areas
0
Cloud Required

### 🎯 Real FFmpeg Operations

Core video paths invoke actual FFmpeg subprocesses — no mocks. If it passes, it works on your machine.

### 🔧 Auto-Fix Error Handling

FFmpeg errors are parsed into structured responses with actionable suggestions. No more cryptic stderr.

### 🛡️ Guardrails Before FFmpeg

Filter bounds, merge compatibility, audio volume/timing, overlay opacity, chroma similarity, animated text overflow, and grid/split-screen mismatches are checked before rendering.

### 📊 Structured Output

Every tool returns JSON with output_path, duration, resolution, bitrate, and codec. Agents always know what happened.