Use when exposing FFmpeg/FFprobe operations as MCP tools so a coding agent can inspect, cut, join, transcode, extract audio, thumbnail, and normalize media without ad hoc shell commands. Local only — no API keys, no cloud.
The first runnable MCP server in this repo — every other mcp/servers/* entry is docs-only. This one ships working Python (server.py) that registers 12 FFmpeg tools via FastMCP, validated end-to-end against real media.
When to Use
Trigger phrases:
"process video with an agent" · "expose ffmpeg as a tool"
"cut / join / transcode media from MCP" · "ffprobe metadata via MCP"
Give an agent a safe, typed surface over FFmpeg instead of raw shell strings
Batch media prep (thumbnails, proxies, frame extraction) inside a tool loop
Loudness normalization before publishing
When NOT to Use
Real-time streaming or live capture (this renders to files)
Heavy GPU encoding pipelines better served by dedicated render farms
Operations needing frame-level scripting — use content/video/remotion instead
Overview
Wraps FFmpeg/FFprobe behind a machine-readable tool contract. No network, no credentials. Each tool builds an argv list and runs it in the foreground with a hard timeout; on failure it raises FFmpegError carrying stderr so the agent sees why.
The 12 tools
Group
Tool
What it does
analysis
probe
Media metadata (codec, w/h, fps, duration, streams) as JSON
editing
cut
Segment [start, end/duration]; stream-copy or frame-accurate reencode
pip install mcp # FastMCP lives in mcp.server.fastmcp
ffmpeg -version && ffprobe -version # must be on PATH
python3 server.py # stdio transport, ready for any MCP client
Register in a client config (Claude Code example):
Probe first. Call probe(path) before any edit — confirm codecs/fps so concat inputs match and cut timings are sane.
Paths. Inputs accept absolute paths or bare names resolved against FFMPEG_MCP_WORKDIR. Outputs default to a suffixed sibling of the source; pass output= to override.
Cut precision. Default cut is stream-copy (fast, snaps to keyframes). Set reencode=true for frame-accurate boundaries at the cost of speed.
Concat constraint.concat uses stream copy, so all inputs MUST share codec/container. Probe each first; mismatched inputs need transcode to a common format beforehand.
Normalize last. Run normalize_audio after all edits — loudnorm re-encodes audio, so do it once at the end.
Verify output. Every tool returns the written path. probe the result if correctness matters.
Error handling
All failures raise FFmpegError with the offending command and tail of stderr:
missing input → input not found: …
binary absent → binary not found on PATH: ffmpeg
timeout → timed out after Ns: …
non-zero exit → exit N … stderr: …
Never backgrounds a process and never invokes a shell — argv is passed directly, so there's no injection surface from quoted filenames.
Anti-Rationalization Table
Rationalization
Reality
"Just let the agent run ffmpeg in bash"
Typed tools prevent malformed flags and give structured errors; raw shell invites quoting bugs and runaway commands.
"Stream-copy is always fine"
It snaps cuts to keyframes — off by up to a GOP. Use reencode=true when the boundary must be exact.
"Concat anything"
Stream-copy concat needs identical codecs. Probe first or transcode to a common format.
"Set concurrency high like Remotion"
FFmpeg already threads internally; the MCP layer serializes. Don't fan out blindly — respect the timeout budget.
"Timeouts don't matter locally"
A bad filtergraph can hang forever. The hard timeout is the safety net.
Verification
python3 -c "import server" loads with no import error
probe on a known file returns valid JSON with width/height/duration
cut, transcode, concat, thumbnail, extract_audio produce readable output files (verified against a generated testsrc2 clip)
Missing-input call raises FFmpegError, not a traceback crash
FFMPEG_MCP_TIMEOUT enforced on a long-running encode
1---2name: ffmpeg-mcp3description: Use when exposing FFmpeg/FFprobe operations as MCP tools so a coding agent can inspect, cut, join, transcode, extract audio, thumbnail, and normalize media without ad hoc shell commands. Local only — no API keys, no cloud.4domain: mcp5author: oyi776license: Apache-2.07subdomain: mcp8tags:9- mcp10- mcp-server11- model-context-protocol12- ffmpeg13- ffprobe14- video15- audio16- media-processing17- tool-integration18version: 1.0.019category: mcp20risk_level: low21human_approval: false22tool_requirements:23- tool: ffmpeg24 purpose: Encode/transcode/cut/concat media25 required: true26- tool: ffprobe27 purpose: Read media metadata28 required: true29metadata:30 source: https://skillmd.com/skills/oyi77/ffmpeg-mcp31---3233# FFmpeg MCP Server3435The first **runnable** MCP server in this repo — every other `mcp/servers/*` entry is docs-only. This one ships working Python (`server.py`) that registers 12 FFmpeg tools via `FastMCP`, validated end-to-end against real media.3637## When to Use3839**Trigger phrases:**40- "process video with an agent" · "expose ffmpeg as a tool"41- "cut / join / transcode media from MCP" · "ffprobe metadata via MCP"42- "normalize loudness" · "make a gif" · "extract frames / audio"4344**Use cases:**45- Give an agent a safe, typed surface over FFmpeg instead of raw shell strings46- Batch media prep (thumbnails, proxies, frame extraction) inside a tool loop47- Loudness normalization before publishing4849## When NOT to Use5051- Real-time streaming or live capture (this renders to files)52- Heavy GPU encoding pipelines better served by dedicated render farms53- Operations needing frame-level scripting — use `content/video/remotion` instead5455## Overview5657Wraps FFmpeg/FFprobe behind a machine-readable tool contract. No network, no credentials. Each tool builds an argv list and runs it in the foreground with a hard timeout; on failure it raises `FFmpegError` carrying stderr so the agent sees why.5859### The 12 tools6061| Group | Tool | What it does |62|---|---|---|63| analysis | `probe` | Media metadata (codec, w/h, fps, duration, streams) as JSON |64| editing | `cut` | Segment [start, end/duration]; stream-copy or frame-accurate reencode |65| editing | `concat` | Join ≥2 same-codec files via concat demuxer |66| picture | `transcode` | Re-encode with codec/CRF/preset + optional scale |67| picture | `compress` | Smaller file; quality low/medium/high → CRF 28/23/18 |68| picture | `thumbnail` | Single still at a timestamp |69| picture | `extract_frames` | PNGs at N fps into a directory |70| picture | `make_gif` | Palette-optimized GIF from a short segment |71| audio | `extract_audio` | Pull audio stream to m4a/mp3/flac |72| audio | `normalize_audio` | loudnorm to target integrated LUFS |73| delivery | `add_subtitles` | Burn SRT/ASS/VTT onto video |74| delivery | `strip_metadata` | Drop metadata + chapters before publishing |7576## Setup7778```bash79pip install mcp # FastMCP lives in mcp.server.fastmcp80ffmpeg -version && ffprobe -version # must be on PATH81python3 server.py # stdio transport, ready for any MCP client82```8384Register in a client config (Claude Code example):8586```json87{88 "mcpServers": {89 "ffmpeg": {90 "command": "python3",91 "args": ["/abs/path/to/mcp/servers/ffmpeg-mcp/server.py"],92 "env": {"FFMPEG_MCP_WORKDIR": "/abs/output/dir", "FFMPEG_MCP_TIMEOUT": "300"}93 }94 }95}96```9798### Env vars99100| Var | Default | Meaning |101|---|---|---|102| `FFMPEG_MCP_WORKDIR` | cwd | Base dir; bare filenames resolve here |103| `FFMPEG_MCP_TIMEOUT` | 300 | Hard per-command seconds; overrun → FFmpegError |104105## Workflow1061071. **Probe first.** Call `probe(path)` before any edit — confirm codecs/fps so `concat` inputs match and `cut` timings are sane.1082. **Paths.** Inputs accept absolute paths or bare names resolved against `FFMPEG_MCP_WORKDIR`. Outputs default to a suffixed sibling of the source; pass `output=` to override.1093. **Cut precision.** Default `cut` is stream-copy (fast, snaps to keyframes). Set `reencode=true` for frame-accurate boundaries at the cost of speed.1104. **Concat constraint.** `concat` uses stream copy, so all inputs MUST share codec/container. Probe each first; mismatched inputs need `transcode` to a common format beforehand.1115. **Normalize last.** Run `normalize_audio` after all edits — loudnorm re-encodes audio, so do it once at the end.1126. **Verify output.** Every tool returns the written path. `probe` the result if correctness matters.113114### Error handling115116All failures raise `FFmpegError` with the offending command and tail of stderr:117- missing input → `input not found: …`118- binary absent → `binary not found on PATH: ffmpeg`119- timeout → `timed out after Ns: …`120- non-zero exit → `exit N … stderr: …`121122Never backgrounds a process and never invokes a shell — argv is passed directly, so there's no injection surface from quoted filenames.123124## Anti-Rationalization Table125126| Rationalization | Reality |127|---|---|128| "Just let the agent run `ffmpeg` in bash" | Typed tools prevent malformed flags and give structured errors; raw shell invites quoting bugs and runaway commands. |129| "Stream-copy is always fine" | It snaps cuts to keyframes — off by up to a GOP. Use `reencode=true` when the boundary must be exact. |130| "Concat anything" | Stream-copy concat needs identical codecs. Probe first or transcode to a common format. |131| "Set concurrency high like Remotion" | FFmpeg already threads internally; the MCP layer serializes. Don't fan out blindly — respect the timeout budget. |132| "Timeouts don't matter locally" | A bad filtergraph can hang forever. The hard timeout is the safety net. |133134## Verification135136- [ ] `python3 -c "import server"` loads with no import error137- [ ] Exactly 12 tools registered (`probe, transcode, cut, extract_audio, thumbnail, make_gif, concat, normalize_audio, compress, extract_frames, add_subtitles, strip_metadata`)138- [ ] `probe` on a known file returns valid JSON with width/height/duration139- [ ] `cut`, `transcode`, `concat`, `thumbnail`, `extract_audio` produce readable output files (verified against a generated `testsrc2` clip)140- [ ] Missing-input call raises `FFmpegError`, not a traceback crash141- [ ] `FFMPEG_MCP_TIMEOUT` enforced on a long-running encode
Run npx get-skill add oyi77/ffmpeg-mcp in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Use when exposing FFmpeg/FFprobe operations as MCP tools so a coding agent can inspect, cut, join, transcode, extract audio, thumbnail, and normalize media without ad hoc shell commands. Local only — no API keys, no cloud. It is listed under DevOps & Infra on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Capability flags: executes scripts. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free. This skill is licensed under Apache-2.
oyi77 (@oyi77) published this skill. Their other Agent Skills are listed on their SkillMD profile.