encodr-mcp
Provides tools for local FFmpeg-based media processing, including probing media, listing codecs, transcoding and remuxing video, transcoding or extracting audio with optional loudness normalization, converting and resizing images, generating thumbnails, burning subtitles, and extracting individual streams.
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., "@encodr-mcp transcode vacation.mp4 to h265 with crf 20"
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.
encodr-mcp
A high-quality, local-first Model Context Protocol server that exposes FFmpeg transcoding to any MCP host (Claude Desktop, Claude Code, …). Everything runs on your machine with open-source codecs — no cloud, no upload, no quality compromise.
Why
LLM agents are great at deciding what to transcode but shouldn't be trusted to hand-write
ffmpeg incantations. encodr-mcp gives the model a small set of safe, well-typed tools with
quality-first defaults baked in — CRF-based encoding, preset slow, sensible pixel formats —
while still allowing full overrides.
Related MCP server: ffmpeg-mcp
Quality policy
All presets use constant-quality (CRF/VBR) encoding, not fixed bitrate — the best quality-per-byte. Defaults target visually-transparent output:
Media | Codec options | Default |
Video |
| H.264 CRF 18, |
Audio |
| Opus 160k VBR |
Image |
| WebP q90 / AVIF CRF 23 |
Nothing is locked — every tool accepts crf, preset, bitrate, quality, scaling, and fps
overrides.
Tools
Tool | What it does |
| Inspect format + streams (compact summary) |
| List supported codecs/formats and their defaults |
| Re-encode video (codec, CRF, scale, fps, audio) |
| Change container with no re-encode (lossless, instant) |
| Re-encode audio, optional EBU R128 loudness normalization |
| Pull the audio track out losslessly |
| Convert/resize images |
| Grab a frame at a timestamp |
| Hardcode subtitles into video |
| Copy a single stream out by index |
Requirements
FFmpeg on your
PATH(ffmpeg+ffprobe). macOS:brew install ffmpeg.Python 3.11+.
FFmpeg builds vary in which encoders/filters they ship. encodr-mcp detects this at runtime
and returns a clear error (e.g. "webp requires the 'libwebp' encoder, which this FFmpeg build was
not compiled with") instead of failing cryptically. In particular, convert_image to WebP needs
libwebp, and burn_subtitles needs an FFmpeg built with libass. A full build (brew install ffmpeg, or most Linux distro packages) includes both.
Install
git clone https://github.com/lakshan-jk/encodr-mcp
cd encodr-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"Run
encodr-mcp # stdio transport
# or
python -m encodr_mcpClaude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"ffmpeg": {
"command": "/absolute/path/to/encodr-mcp/.venv/bin/encodr-mcp"
}
}
}Claude Code
claude mcp add ffmpeg -- /absolute/path/to/encodr-mcp/.venv/bin/encodr-mcpSecurity / sandboxing
By default the server can read and write anywhere your user can. To confine all input/output paths to one directory tree, set:
export ENCODR_MCP_ROOT=/path/to/allowed/dirAny path outside that root is rejected. Commands are always executed with an explicit argument list (never a shell string), so filenames can't inject shell commands.
Development
pytest # unit tests + ffmpeg integration tests (auto-skipped if no ffmpeg)
ruff check .
mypyLicense
MIT © Lakshan Kumar JK
Available Tools
10 toolsburn_subtitlesC
Burn (hardcode) a subtitle file into the video. Audio is copied unchanged.
Inputs: input (required), output (required), subtitles (required), overwrite. Returns: object
convert_imageC
Convert/resize an image. Formats: webp, avif, jpeg, png (lossless).
For webp/jpeg, quality is 0-100; for avif, quality is a CRF-like value.
Inputs: fmt (required), input (required), output (required), width, +3 more. Returns: object
extract_audioB
Extract the audio track from a video losslessly (stream copy).
Inputs: input (required), output (required), overwrite. Returns: object
extract_streamA
Extract a single stream (by absolute index from probe_media) losslessly.
Inputs: index (required), input (required), output (required), overwrite. Returns: object
list_codecsA
List the supported video/audio codecs and image formats with their quality defaults.
Inputs: no named parameters. Returns: object
probe_mediaB
Inspect a media file and return a compact summary of its format and streams.
Inputs: path (required). Returns: object
remux_videoB
Change a video's container (e.g. .mkv -> .mp4) with no re-encode. Lossless and fast.
Inputs: input (required), output (required), overwrite. Returns: object
thumbnailC
Grab a single high-quality frame from a video at timestamp at (HH:MM:SS).
Inputs: input (required), output (required), at, width, +1 more. Returns: object
transcode_audioC
Transcode audio. Codecs: opus (default), aac, mp3, flac (lossless), wav.
Set normalize=true for EBU R128 loudness normalization (-16 LUFS).
Inputs: input (required), output (required), codec, bitrate, +4 more. Returns: object
transcode_videoA
Transcode a video. Quality is CRF-based (lower crf = higher quality).
Codecs: h264 (default, universal), h265, av1 (best compression), vp9. Optionally downscale with scale_height (e.g. 1080) or change fps.
Inputs: input (required), output (required), crf, fps, +6 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool has a largely distinct action: probe vs. list, transcode vs. remux, audio vs. video. The only real overlap is extract_audio versus extract_stream (which can also pull an audio stream by index), and thumbnail vs. extract_stream for frame grabbing, but the descriptions make the intended boundaries clear enough.
Nine of ten tools follow a clean snake_case verb_noun pattern (probe_media, transcode_video, extract_audio, convert_image, burn_subtitles). 'thumbnail' is the lone bare noun, a minor deviation from an otherwise predictable convention.
Ten tools is well-scoped for a media encoding server, covering inspection, listing, video/audio transcoding, remuxing, extraction, image conversion, thumbnails, and subtitles without padding. Each tool maps to a concrete operation a user would need.
The core encode/convert lifecycle is well covered, including probe, codec discovery, transcode, remux, extract, and subtitle burn-in. Minor gaps exist around trimming/cutting to a time range, concatenating files, and extracting subtitle streams, but none are dead ends for typical workflows.
Maintenance
Related MCP Connectors
Hosted MCP tools for FFmpeg-style video and audio processing through FFMPEG API.
FFmpeg processing for video, audio and images via MCP with OAuth and shared account allowance.
MCP server for the FFmpeg Micro video transcoding API — create, monitor, download transcodes.
FFmpeg Micro - The FFmpeg Api - www.ffmpeg-micro.com Transcode videos from n8n or Make using FFmpeg in the cloud. MCP Server: https://github.com/ffmpeg-micro/ffmpeg-micro-mcp/
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables comprehensive video and audio processing using FFmpeg, supporting tasks like metadata extraction, clipping, scaling, and adding transitions or overlays. It provides a high-performance interface for building media processing microservices via FastMCP.1212-
- FlicenseNot gradedqualityDmaintenanceEnables comprehensive video/audio processing, analysis, and streaming via natural language by exposing 40+ FFmpeg tools as MCP tools.23-
- AlicenseAqualityDmaintenanceProvides 30+ FFmpeg video and audio editing tools via MCP, enabling AI assistants to perform operations like trimming, transcoding, overlays, and composition directly.274MIT
- AlicenseNot gradedqualityDmaintenanceMCP server exposing headless ffmpeg operations for video, audio, and image processing via auto-generated typed tools, enabling agentic media file manipulation.GPL 3.0