FFmpeg video & audio editing tools via Model Context Protocol (MCP)
Give your AI assistant the power to edit video and audio — trim, transcode, overlay, compose, and more.
AI assistants are great at understanding what you want to do with media files, but they can't actually do it — until now. MCP-FFmpeg bridges the gap by exposing 30+ FFmpeg operations as MCP tools that any compatible AI assistant can call directly.
You: "Trim this video from 00:30 to 02:00, add a fade-in, and convert to 720p"
AI: Calls trim_video → add_basic_transitions → set_video_resolution → Done!
┌─────────────────────┐ MCP Protocol ┌──────────────────────────┐
│ AI Assistants │◄───────────────────► │ mcp-ffmpeg Server │
│ │ JSON-RPC/stdio │ │
│ · Claude Code │ │ ┌────────┐ ┌────────┐ │
│ · Claude Desktop │ │ │ Video │ │ Audio │ │
│ · Cursor │ │ │ Tools │ │ Tools │ │
│ · Any MCP Client │ │ └────────┘ └────────┘ │
└─────────────────────┘ │ ┌────────┐ ┌────────┐ │
│ │Overlay │ │Compose │ │
│ │ Tools │ │ Tools │ │
│ └────────┘ └────────┘ │
└──────────┬─────────────┘
│
▼
┌──────────────────────┐
│ FFmpeg Engine │
└──────────────────────┘
| Requirement | Version | Purpose |
|---|---|---|
| Python | 3.10+ | Runtime |
| FFmpeg | Any recent | Media processing engine |
| uv | Latest | Python package manager (recommended) |
git clone https://github.com/kevinten-ai/mcp-ffmpeg.git
cd mcp-ffmpeg
uv sync
uv run python main.pyAdd to your project's .mcp.json:
{
"mcpServers": {
"ffmpeg-tools": {
"command": "uv",
"args": ["--directory", "/path/to/mcp-ffmpeg", "run", "python", "main.py"]
}
}
}Add to claude_desktop_config.json:
{
"mcpServers": {
"ffmpeg-tools": {
"command": "uv",
"args": ["--directory", "/path/to/mcp-ffmpeg", "run", "python", "main.py"]
}
}
}Use the same server configuration — any client that supports MCP's stdio transport will work.
| Tool | Description |
|---|---|
trim_video |
Trim video to specific start/end times |
convert_video_format |
Convert between formats (mp4, mov, avi, etc.) |
convert_video_properties |
Batch convert format, resolution, codecs, bitrate, frame rate |
change_aspect_ratio |
Change aspect ratio with pad or crop mode |
set_video_resolution |
Scale to target resolution (e.g., 1920x1080) |
set_video_codec |
Change video codec (libx264, libx265, vp9) |
set_video_bitrate |
Set video bitrate (e.g., 2500k, 5M) |
set_video_frame_rate |
Adjust frame rate (24, 30, 60 fps) |
change_video_speed |
Speed up or slow down playback (0.25x to 4x+) |
| Tool | Description |
|---|---|
extract_audio_from_video |
Extract audio track from video file |
convert_audio_format |
Convert between audio formats (mp3, wav, aac) |
convert_audio_properties |
Batch convert format, bitrate, sample rate, channels |
set_audio_bitrate |
Set audio bitrate (128k, 192k, 320k) |
set_audio_sample_rate |
Set sample rate (44100, 48000 Hz) |
set_audio_channels |
Set mono (1) or stereo (2) |
| Tool | Description |
|---|---|
set_video_audio_track_codec |
Change audio codec within video (aac, mp3) |
set_video_audio_track_bitrate |
Set audio bitrate within video |
set_video_audio_track_sample_rate |
Set audio sample rate within video |
set_video_audio_track_channels |
Set audio channels within video |
| Tool | Description |
|---|---|
add_text_overlay |
Add timed text overlays with full styling control |
add_image_overlay |
Add image watermarks/logos with position & opacity |
add_subtitles |
Burn SRT subtitles with customizable font styling |
| Tool | Description |
|---|---|
concatenate_videos |
Join multiple videos with optional xfade transitions |
add_b_roll |
Insert B-roll clips as overlays at specific timestamps |
add_basic_transitions |
Add fade-in / fade-out effects |
remove_silence |
Detect and remove silent segments automatically |
| Tool | Description |
|---|---|
health_check |
Verify server is running and responsive |
"Trim intro.mp4 from 10s to 2:30 and save as intro_trimmed.mp4"
→ trim_video(video_path="intro.mp4", output_video_path="intro_trimmed.mp4",
start_time="10", end_time="2:30")
"Convert recording.mov to mp4 at 720p with h265 codec"
→ convert_video_properties(input_video_path="recording.mov",
output_video_path="recording.mp4",
target_format="mp4", resolution="720",
video_codec="libx265")
"Burn subtitles.srt onto my video with large white text"
→ add_subtitles(video_path="video.mp4", srt_file_path="subtitles.srt",
output_video_path="video_subtitled.mp4",
font_style={"font_size": 28, "font_color": "&HFFFFFF"})
"Join clip1.mp4 and clip2.mp4 with a dissolve transition"
→ concatenate_videos(video_paths=["clip1.mp4", "clip2.mp4"],
output_video_path="final.mp4",
transition_effect="dissolve",
transition_duration=1.0)
The concatenate_videos tool supports 30+ xfade transitions for joining two videos:
| Category | Transitions |
|---|---|
| Fade | fade, fadeblack, fadewhite, fadegrays, dissolve, distance |
| Wipe | wipeleft, wiperight, wipeup, wipedown |
| Slide | slideleft, slideright, slideup, slidedown |
| Smooth | smoothleft, smoothright, smoothup, smoothdown |
| Shape | circlecrop, rectcrop, circleopen, circleclose |
| Split | vertopen, vertclose, horzopen, horzclose |
| Diagonal | diagtl, diagtr, diagbl, diagbr |
| Slice | hlslice, hrslice, vuslice, vdslice |
| Other | pixelize, radial, hblur |
mcp-ffmpeg/
├── main.py # Entry point
├── pyproject.toml # Project config & dependencies
├── src/ffmpeg_tools/
│ ├── __init__.py
│ ├── server.py # MCP server setup & tool registration
│ ├── utils.py # Shared utilities (probe, clip prep, etc.)
│ └── tools/
│ ├── audio.py # Audio processing tools (6 tools)
│ ├── video.py # Video & video-audio tools (13 tools)
│ ├── overlay.py # Text/image/subtitle overlay tools (3 tools)
│ └── compose.py # Concatenation, B-roll, transitions (4 tools)
├── tests/
│ ├── test_video_functions.py # Test suite
│ └── sample_files/ # Test media files
└── assets/ # Images for documentation
uv run pytest tests/ -vContributions are welcome! Here are some ways to help:
- Add new FFmpeg tools (e.g., video stabilization, noise reduction)
- Improve error handling and validation
- Add more test coverage
- Improve documentation
MIT License — see LICENSE for details.
Based on video-audio-mcp by misbahsy.