Provides video and audio editing capabilities via FFmpeg, including trimming, transcoding, overlays, composition, and more.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-ffmpeg Trim video from 1:00 to 2:30 and convert to mp4"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Quick Start · Tools · Configuration · Architecture
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!Related MCP server: ffmpeg-mcp
┌─────────────────────┐ 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 to specific start/end times |
| Convert between formats (mp4, mov, avi, etc.) |
| Batch convert format, resolution, codecs, bitrate, frame rate |
| Change aspect ratio with pad or crop mode |
| Scale to target resolution (e.g., 1920x1080) |
| Change video codec (libx264, libx265, vp9) |
| Set video bitrate (e.g., 2500k, 5M) |
| Adjust frame rate (24, 30, 60 fps) |
| Speed up or slow down playback (0.25x to 4x+) |
Tool | Description |
| Extract audio track from video file |
| Convert between audio formats (mp3, wav, aac) |
| Batch convert format, bitrate, sample rate, channels |
| Set audio bitrate (128k, 192k, 320k) |
| Set sample rate (44100, 48000 Hz) |
| Set mono (1) or stereo (2) |
Tool | Description |
| Change audio codec within video (aac, mp3) |
| Set audio bitrate within video |
| Set audio sample rate within video |
| Set audio channels within video |
Tool | Description |
| Add timed text overlays with full styling control |
| Add image watermarks/logos with position & opacity |
| Burn SRT subtitles with customizable font styling |
Tool | Description |
| Join multiple videos with optional xfade transitions |
| Insert B-roll clips as overlays at specific timestamps |
| Add fade-in / fade-out effects |
| Detect and remove silent segments automatically |
Tool | Description |
| 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 |
|
Wipe |
|
Slide |
|
Smooth |
|
Shape |
|
Split |
|
Diagonal |
|
Slice |
|
Other |
|
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 documentationuv 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.
Adds basic fade transitions to the beginning or end of a video.
Args: video_path: Path to the input video file. output_video_path: Path to save the video with the transition. transition_type: Type of transition. Options: 'fade_in', 'fade_out'. duration_seconds: Duration of the fade effect in seconds. Returns: A status message indicating success or failure.
Inputs: video_path (required), transition_type (required), duration_seconds (required), output_video_path (required). Returns: result
Inserts B-roll clips into a main video as overlays.
Args: main_video_path: Path to the main video file. broll_clips: A list of dicts, each with keys: Required: 'clip_path' (str), 'insert_at_timestamp' (str/float). Optional: 'duration' (str/float), 'position' ('fullscreen'|'top-left'|'top-right'| 'bottom-left'|'bottom-right'|'center'), 'scale' (float), 'transition_in'/'transition_out' ('fade'), 'transition_duration' (float), 'audio_mix' (float, 0.0-1.0). output_video_path: The path to save the output video. Returns: A status message indicating success or failure.
Inputs: broll_clips (required), main_video_path (required), output_video_path (required). Returns: result
Adds an image overlay (watermark/logo) to a video.
Args: video_path: Path to the input video file. output_video_path: Path to save the video with the image overlay. image_path: Path to the image file for the overlay. position: Position of the overlay. Options: 'top_left', 'top_right', 'bottom_left', 'bottom_right', 'center'. Or specify custom coordinates like 'x=10:y=10'. opacity: Opacity of the overlay (0.0 to 1.0). If None, image's own alpha is used. start_time: Start time for the overlay (HH:MM:SS or seconds). If None, starts from beginning. end_time: End time for the overlay (HH:MM:SS or seconds). If None, lasts till end. width: Width for the overlay image (e.g., '100', 'iw0.1'). Original if None. height: Height for the overlay image (e.g., '50', 'ih0.1'). Original if None. Returns: A status message indicating success or failure.
Inputs: image_path (required), video_path (required), output_video_path (required), width, +5 more. Returns: result
Burns subtitles from an SRT file onto a video, with optional styling.
Args: video_path: Path to the input video file. srt_file_path: Path to the SRT subtitle file. output_video_path: Path to save the video with subtitles. font_style (dict, optional): A dictionary for subtitle styling. Supported keys: 'font_name', 'font_size', 'font_color', 'outline_color', 'outline_width', 'shadow_color', 'shadow_offset_x', 'shadow_offset_y', 'alignment', 'margin_v', 'margin_l', 'margin_r'. Default is None, which uses FFmpeg's default subtitle styling. Returns: A status message indicating success or failure.
Inputs: video_path (required), srt_file_path (required), output_video_path (required), font_style. Returns: result
Adds one or more text overlays to a video at specified times and positions.
Args: video_path: Path to the input main video file. output_video_path: Path to save the video with text overlays. text_elements: A list of dictionaries, where each dictionary defines a text overlay. Required keys: 'text', 'start_time', 'end_time'. Optional keys: 'font_size' (24), 'font_color' ('white'), 'x_pos' ('center'), 'y_pos' ('h-th-10'), 'box' (False), 'box_color' ('black@0.5'), 'box_border_width' (0), 'font_file'. Returns: A status message indicating success or failure.
Inputs: video_path (required), text_elements (required), output_video_path (required). Returns: result
Changes the aspect ratio of a video, using padding or cropping.
Args: video_path: Path to the input video file. output_video_path: Path to save the video with the new aspect ratio. target_aspect_ratio: Target aspect ratio (e.g., '16:9', '4:3', '1:1'). resize_mode: 'pad' to add letterbox/pillarbox, or 'crop' to crop. Defaults to 'pad'. padding_color: Color for padding (e.g., 'black', 'white'). Defaults to 'black'. Returns: A status message indicating success or failure.
Inputs: video_path (required), output_video_path (required), target_aspect_ratio (required), resize_mode, +1 more. Returns: result
Changes the playback speed of a video (and its audio).
Args: video_path: Path to the input video file. output_video_path: Path to save the speed-adjusted video file. speed_factor: The factor by which to change the speed (e.g., 2.0 for 2x speed, 0.5 for half speed). Must be positive. Returns: A status message indicating success or failure.
Inputs: video_path (required), speed_factor (required), output_video_path (required). Returns: result
Concatenates multiple video files into a single output file. Supports optional xfade transition when concatenating exactly two videos.
Args: video_paths: A list of paths to the video files to concatenate. output_video_path: The path to save the concatenated video file. transition_effect: The xfade transition type (e.g., 'dissolve', 'fade', 'wipeleft'). Only applied if exactly two videos are provided. Defaults to None. transition_duration: The duration of the xfade transition in seconds. Required if transition_effect is specified. Returns: A status message indicating success or failure.
Inputs: video_paths (required), output_video_path (required), transition_effect, transition_duration. Returns: result
Converts an audio file to the specified target format.
Args: input_audio_path: Path to the source audio file. output_audio_path: Path to save the converted audio file. target_format: Desired output audio format (e.g., 'mp3', 'wav', 'aac'). Returns: A status message indicating success or failure.
Inputs: target_format (required), input_audio_path (required), output_audio_path (required). Returns: result
Converts audio file format and ALL specified properties like bitrate, sample rate, and channels.
Args: input_audio_path: Path to the source audio file. output_audio_path: Path to save the converted audio file. target_format: Desired output audio format (e.g., 'mp3', 'wav', 'aac'). bitrate: Target audio bitrate (e.g., '128k', '192k'). Optional. sample_rate: Target audio sample rate in Hz (e.g., 44100, 48000). Optional. channels: Number of audio channels (1 for mono, 2 for stereo). Optional. Returns: A status message indicating success or failure.
Inputs: target_format (required), input_audio_path (required), output_audio_path (required), bitrate, +2 more. Returns: result
Converts a video file to the specified target format, attempting to copy codecs first.
Args: input_video_path: Path to the source video file. output_video_path: Path to save the converted video file. target_format: Desired output video format (e.g., 'mp4', 'mov', 'avi'). Returns: A status message indicating success or failure.
Inputs: target_format (required), input_video_path (required), output_video_path (required). Returns: result
Converts video file format and ALL specified properties like resolution, codecs, bitrates, and frame rate.
Args: input_video_path: Path to the source video file. output_video_path: Path to save the converted video file. target_format: Desired output video format (e.g., 'mp4', 'mov', 'avi'). resolution: Target resolution (e.g., '1920x1080' or '720' for height). Optional. video_codec: Target video codec (e.g., 'libx264', 'libx265'). Optional. video_bitrate: Target video bitrate (e.g., '1M', '2500k'). Optional. frame_rate: Target frame rate (e.g., 24, 30, 60). Optional. audio_codec: Target audio codec (e.g., 'aac', 'mp3'). Optional. audio_bitrate: Target audio bitrate (e.g., '128k', '192k'). Optional. audio_sample_rate: Target audio sample rate in Hz (e.g., 44100, 48000). Optional. audio_channels: Number of audio channels (1 for mono, 2 for stereo). Optional. Returns: A status message indicating success or failure.
Inputs: target_format (required), input_video_path (required), output_video_path (required), frame_rate, +7 more. Returns: result
Extracts audio from a video file and saves it.
Args: video_path: The path to the input video file. output_audio_path: The path to save the extracted audio file. audio_codec: The audio codec to use for the output (e.g., 'mp3', 'aac', 'wav'). Defaults to 'mp3'. Returns: A status message indicating success or failure.
Inputs: video_path (required), output_audio_path (required), audio_codec. Returns: result
Returns a simple health status to confirm the server is running.
Inputs: no named parameters. Returns: result
Removes silent segments from an audio or video file.
Args: media_path: Path to the input audio or video file. output_media_path: Path to save the media file with silences removed. silence_threshold_db: The noise level (in dBFS) below which is considered silence. min_silence_duration_ms: Minimum duration (in milliseconds) of silence to be removed. Returns: A status message indicating success or failure.
Inputs: media_path (required), output_media_path (required), silence_threshold_db, min_silence_duration_ms. Returns: result
Sets the bitrate for an audio file.
Args: input_audio_path: Path to the source audio file. output_audio_path: Path to save the audio file with the new bitrate. bitrate: Target audio bitrate (e.g., '128k', '192k', '320k'). Returns: A status message indicating success or failure.
Inputs: bitrate (required), input_audio_path (required), output_audio_path (required). Returns: result
Sets the number of channels for an audio file (1 for mono, 2 for stereo).
Args: input_audio_path: Path to the source audio file. output_audio_path: Path to save the audio file with the new channel layout. channels: Number of audio channels (1 for mono, 2 for stereo). Returns: A status message indicating success or failure.
Inputs: channels (required), input_audio_path (required), output_audio_path (required). Returns: result
Sets the sample rate for an audio file.
Args: input_audio_path: Path to the source audio file. output_audio_path: Path to save the audio file with the new sample rate. sample_rate: Target audio sample rate in Hz (e.g., 44100, 48000). Returns: A status message indicating success or failure.
Inputs: sample_rate (required), input_audio_path (required), output_audio_path (required). Returns: result
Sets the audio bitrate of a video's audio track, attempting to copy the video stream.
Args: input_video_path: Path to the source video file. output_video_path: Path to save the video with the new audio bitrate. audio_bitrate: Target audio bitrate (e.g., '128k', '192k'). Returns: A status message indicating success or failure.
Inputs: audio_bitrate (required), input_video_path (required), output_video_path (required). Returns: result
Sets the number of audio channels of a video's audio track, attempting to copy the video stream.
Args: input_video_path: Path to the source video file. output_video_path: Path to save the video with the new audio channel layout. audio_channels: Number of audio channels (1 for mono, 2 for stereo). Returns: A status message indicating success or failure.
Inputs: audio_channels (required), input_video_path (required), output_video_path (required). Returns: result
Sets the audio codec of a video's audio track, attempting to copy the video stream.
Args: input_video_path: Path to the source video file. output_video_path: Path to save the video with the new audio codec. audio_codec: Target audio codec (e.g., 'aac', 'mp3'). Returns: A status message indicating success or failure.
Inputs: audio_codec (required), input_video_path (required), output_video_path (required). Returns: result
Sets the audio sample rate of a video's audio track, attempting to copy the video stream.
Args: input_video_path: Path to the source video file. output_video_path: Path to save the video with the new audio sample rate. audio_sample_rate: Target audio sample rate in Hz (e.g., 44100, 48000). Returns: A status message indicating success or failure.
Inputs: input_video_path (required), audio_sample_rate (required), output_video_path (required). Returns: result
Sets the video bitrate of a video, attempting to copy the audio stream.
Args: input_video_path: Path to the source video file. output_video_path: Path to save the video with the new video bitrate. video_bitrate: Target video bitrate (e.g., '1M', '2500k'). Returns: A status message indicating success or failure.
Inputs: video_bitrate (required), input_video_path (required), output_video_path (required). Returns: result
Sets the video codec of a video, attempting to copy the audio stream.
Args: input_video_path: Path to the source video file. output_video_path: Path to save the video with the new video codec. video_codec: Target video codec (e.g., 'libx264', 'libx265', 'vp9'). Returns: A status message indicating success or failure.
Inputs: video_codec (required), input_video_path (required), output_video_path (required). Returns: result
Sets the frame rate of a video, attempting to copy the audio stream.
Args: input_video_path: Path to the source video file. output_video_path: Path to save the video with the new frame rate. frame_rate: Target video frame rate (e.g., 24, 30, 60). Returns: A status message indicating success or failure.
Inputs: frame_rate (required), input_video_path (required), output_video_path (required). Returns: result
Sets the resolution of a video, attempting to copy the audio stream.
Args: input_video_path: Path to the source video file. output_video_path: Path to save the video with the new resolution. resolution: Target video resolution (e.g., '1920x1080', '1280x720', or '720' for height). Returns: A status message indicating success or failure.
Inputs: resolution (required), input_video_path (required), output_video_path (required). Returns: result
Trims a video to the specified start and end times.
Args: video_path: The path to the input video file. output_video_path: The path to save the trimmed video file. start_time: The start time for trimming (HH:MM:SS or seconds). end_time: The end time for trimming (HH:MM:SS or seconds). Returns: A status message indicating success or failure.
Inputs: end_time (required), start_time (required), video_path (required), output_video_path (required). Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 27 tools
Several tools have overlapping purposes, such as the single-property setters (set_audio_sample_rate, set_audio_bitrate, etc.) versus the all-in-one converters (convert_audio_properties, convert_video_properties). The descriptions help clarify usage, but an agent could easily select the wrong tool when simple format conversion is needed because both convert_audio_format and convert_audio_properties perform that task.
Tool names mostly follow a verb_noun pattern (set_*, convert_*, add_*), with clear prefixes for different actions. There are minor deviations like 'change_aspect_ratio' and 'change_video_speed' instead of 'set_*', and 'health_check' does not fit the pattern, but overall the naming is predictable and readable.
At 27 tools, the server is on the higher end, but the breadth of FFmpeg operations justifies many of them. However, the count is inflated by redundant single-property setters that could be consolidated into the existing property conversion tools, making the set feel heavier than necessary.
The server covers a wide range of common media operations: audio/video format conversion, property adjustments, trimming, speed changes, overlays, subtitles, concatenation, and silence removal. Minor gaps exist, such as video rotation or cropping to specific dimensions, but the core workflows are well represented.
Hosted MCP tools for FFmpeg-style video and audio processing through FFMPEG API.
FFmpeg as a service for AI agents: typed video editing tools, async jobs, downloadable outputs.
AI video, image and audio generation with 140+ AI models from any MCP agent
Video, audio, and image processing for AI agents: convert, transcribe, upscale - 150+ operations.
