Allows AI agents using OpenAI's API to perform FFmpeg media operations (clip, merge, extract audio, add subtitles, transcode) via function calling.
Click on "Install 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., "@ff-toolkit extract audio from video.mp4 to audio.mp3"
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 operations as LLM-callable tools.
Stop hand-writing FFmpeg subprocess calls and JSON tool schemas.
ff-toolkitgives you 5 production-ready media operations, dual-format LLM schemas (OpenAI + Anthropic), and an MCP server — all in onepip install.
"My agent pipeline needs to process uploaded videos" — Give your agent openai_tools() or anthropic_tools() and let it decide how to clip, transcode, or extract audio. The dispatch() function handles execution.
"I need to batch-extract 16kHz WAV for ASR" — One line: extract_audio("video.mp4", "out.wav", codec="pcm_s16le", sample_rate=16000, channels=1)
"I want FFmpeg tools in Claude Desktop / Cursor" — Add the MCP server config (3 lines of JSON) and Claude can edit your videos directly.
"I want FFmpeg tools in DeepSeek Harness" — dsh plugin add dsh-ffkit installs the native plugin from integrations/deepseek-harness.
"I'm tired of writing the same FFmpeg commands" — Use the CLI: ffkit clip input.mp4 output.mp4 --start 00:01:00 --duration 30
Related MCP server: ffmpeg-mcp
# Install (requires FFmpeg on PATH)
pip install ff-toolkit
# Verify it works — no API keys needed
ffkit probe some_video.mp4
# Or run the full demo with a generated test video
python -m ff_kit.examples.localfrom ff_kit import clip, extract_audio, merge, transcode
# Trim seconds 60-90
clip("raw.mp4", "highlight.mp4", start="00:01:00", duration="30")
# Extract 16kHz mono audio for Whisper/Paraformer
extract_audio("raw.mp4", "speech.wav", codec="pcm_s16le", sample_rate=16000, channels=1)
# Concatenate intro + main + outro
merge(["intro.mp4", "main.mp4", "outro.mp4"], "final.mp4")
# Compress to 720p WebM for web delivery
transcode("raw.mp4", "web.webm", video_codec="libvpx-vp9", resolution="1280x720", crf=30)ffkit clip raw.mp4 highlight.mp4 --start 00:01:00 --duration 30
ffkit extract-audio raw.mp4 speech.wav --codec pcm_s16le --sample-rate 16000 --channels 1
ffkit merge intro.mp4 main.mp4 outro.mp4 -o final.mp4
ffkit transcode raw.mp4 web.webm --video-codec libvpx-vp9 --resolution 1280x720 --crf 30
ffkit probe video.mp4from ff_kit.schemas.openai import openai_tools
from ff_kit.dispatch import dispatch
# 1. Pass tools to the model
response = client.chat.completions.create(
model="gpt-4o",
messages=messages,
tools=openai_tools(), # ← that's it
)
# 2. Execute whatever the model calls
tc = response.choices[0].message.tool_calls[0]
result = dispatch(tc.function.name, json.loads(tc.function.arguments))from ff_kit.schemas.anthropic import anthropic_tools
from ff_kit.dispatch import dispatch
response = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
tools=anthropic_tools(), # ← that's it
messages=messages,
)
for block in response.content:
if block.type == "tool_use":
result = dispatch(block.name, block.input)Add to your config (claude_desktop_config.json or Cursor settings):
{
"mcpServers": {
"ff-toolkit": {
"command": "ffkit-mcp",
"args": []
}
}
}That's it. Claude can now clip, merge, extract audio, add subtitles, and transcode your files.
DeepSeek Harness (dsh) is DeepSeek's plugin-based agent runtime. ff-toolkit ships a native dsh plugin — the dsh-ffkit npm package in integrations/deepseek-harness:
pip install ff-toolkit # the Python side (this package)
dsh plugin --profile <name> add dsh-ffkit # the harness sideThe plugin registers all five operations as typed harness tools with structured canonical outputs (usable from dsh Code Mode) and UI cards. Under the hood each call runs python -m ff_kit.bridge, a one-shot JSON entry point over stdin/stdout that any host runtime can reuse. See the plugin README for configuration.
Tool | What it does | Example |
| Trim a segment by start + end/duration | Cut highlight reel from raw footage |
| Concatenate multiple files | Join intro + content + outro |
| Extract audio, optionally re-encode | Get 16kHz WAV for speech recognition |
| Burn or embed subtitles (.srt/.ass/.vtt) | Hard-sub a translated SRT into video |
| Convert format, codec, resolution, bitrate | Compress 4K MP4 to 720p WebM for web |
Your Agent ff-toolkit FFmpeg
│ │ │
├─ openai_tools() ──────────┤ │
│ or anthropic_tools() │ │
│ │ │
├─ LLM returns tool call ──►│ │
│ │ │
├─ dispatch(name, args) ───►├─ validates & builds cmd ────►│
│ │ │
│◄── FFmpegResult ─────────┤◄── subprocess result ────────┤
│ │ │ff-toolkit/
├── src/ff_kit/
│ ├── __init__.py # Public API: clip, merge, extract_audio, ...
│ ├── cli.py # CLI entry point (ffkit command)
│ ├── executor.py # FFmpeg subprocess runner + probe
│ ├── dispatch.py # Tool name → function router
│ ├── bridge.py # One-shot JSON bridge (stdin/stdout) for host runtimes
│ ├── core/ # One module per operation
│ │ ├── clip.py
│ │ ├── merge.py
│ │ ├── extract_audio.py
│ │ ├── add_subtitles.py
│ │ └── transcode.py
│ ├── schemas/ # LLM tool definitions
│ │ ├── openai.py # OpenAI function-calling format
│ │ └── anthropic.py # Anthropic tool-use format
│ └── mcp/ # MCP server (stdio JSON-RPC)
│ └── server.py
├── examples/
│ ├── local_example.py # ← Run this first! No API key needed
│ ├── openai_example.py
│ ├── anthropic_example.py
│ └── agent_loop_example.py
├── tests/ # 49 tests, all mocked (no FFmpeg needed)
└── integrations/
└── deepseek-harness/ # dsh-ffkit npm package (DeepSeek Harness plugin)git clone https://github.com/inthepond/ff-toolkit.git
cd ff-toolkit
pip install -e ".[dev]"
pytest -v # 49 tests, runs in <1sQ: Do I need FFmpeg installed?
Yes, for actual media operations. Tests are fully mocked and don't need FFmpeg. Install it from ffmpeg.org/download or brew install ffmpeg / apt install ffmpeg.
Q: Can I add custom operations?
Yes — add a function in core/, register it in dispatch.py's _REGISTRY, and add schema entries in schemas/openai.py and schemas/anthropic.py. See any existing operation as a template.
Q: Why not just use LangChain / CrewAI tools? Those frameworks are great, but they're heavy dependencies. ff-toolkit is zero-dependency (beyond Python stdlib) and works with any LLM provider. You can use it inside LangChain if you want, or standalone.
Q: What about streaming / progress callbacks? Not in v0.1. FFmpeg progress parsing is planned for v0.2.
MIT
Add subtitles to a video. 'burn' hard-codes into pixels; 'embed' adds as a soft subtitle track.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Subtitle mode. Default: burn. | |
| input_path | Yes | Source video file. | |
| output_path | Yes | Output video file. | |
| subtitle_path | Yes | Path to subtitle file (.srt, .ass, .vtt). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the two behavioral modes, clarifying that 'burn' permanently alters pixels. For a non-destructive operation like 'embed', no further behavioral caveats are needed, but some details about encoding support could improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence—front-loaded with the purpose, followed by clarification of the key parameter. Every word adds value with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with 100% schema coverage, 3 required parameters, and no output schema, the description is complete. It explains the purpose, the critical mode parameter, and the supported subtitle formats. No further information about return values is needed since there is no output schema, and the tool's effect is straightforward.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter (input_path, output_path, subtitle_path, mode) already has a description. The description adds value by explaining the enum values 'burn' and 'embed' more concretely, but does not provide extra semantics for the path parameters beyond what the schema already defines.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'add' and the resource 'subtitles to a video'. It distinguishes between the two modes 'burn' and 'embed', explaining their effects. This helps differentiate from sibling tools like ffkit_clip, ffkit_extract_audio, ffkit_merge, and ffkit_transcode.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly guides usage by explaining when to use 'burn' (hard-coding into pixels) vs 'embed' (soft subtitle track). This helps the agent choose the appropriate mode, but does not explicitly state when not to use this tool or suggest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trim a segment from a media file. Specify start + end or start + duration. Time format: HH:MM:SS.ms or seconds.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | End timestamp. Mutually exclusive with duration. | |
| start | Yes | Start timestamp (e.g. '00:01:30' or '90'). | |
| duration | No | Duration of the clip. Mutually exclusive with end. | |
| input_path | Yes | Path to the source media file. | |
| output_path | Yes | Path for the trimmed output file. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly states the effect (trimming a segment) and specifies time format constraints (HH:MM:SS.ms or seconds). It does not cover side effects, output format, or whether the operation modifies the original file, but given the lack of annotations, the description's transparency is strong for a simple trimming tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, with zero waste. Each sentence provides essential information: the action and the parameter alternatives plus time format. It is well front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (5 parameters, 3 required), no output schema, and no annotations, the description covers core usage adequately. It explains the trimming operation, parameter combinations, and time format. It could be improved by noting expected output format or that the operation is non-destructive, but it is largely complete for a straightforward trimming tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds some value by explaining the mutual exclusivity of end and duration, and by specifying allowed time formats. However, it does not clarify what happens if both end and duration are omitted or both provided beyond the schema's 'mutually exclusive' hints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('Trim a segment from a media file') and clearly identifies the resource (media file). It also distinguishes the tool from siblings by stating the action (trim) as opposed to adding subtitles, extracting audio, merging, or transcoding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides basic usage context (trim a segment) and mentions the two mutually exclusive parameter groups (start+end or start+duration). However, it does not differentiate from sibling tools explicitly, nor does it state when not to use this tool (e.g., for concatenation or format conversion).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract the audio stream from a video/audio file. Can re-encode to a different codec or keep original.
| Name | Required | Description | Default |
|---|---|---|---|
| codec | No | Audio codec. 'copy' keeps original; or 'libmp3lame', 'aac', 'pcm_s16le'. | |
| channels | No | Number of audio channels (1=mono, 2=stereo). | |
| input_path | Yes | Source media file. | |
| output_path | Yes | Destination audio file (e.g. 'out.mp3', 'out.wav'). | |
| sample_rate | No | Output sample rate in Hz (e.g. 16000 for ASR). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the core operation but does not disclose whether the operation is destructive, whether it requires specific permissions, what happens to the original file, or any side effects (e.g., temporary files, licensing). The description is minimal and does not add behavioral context beyond the action itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the primary action. Every word contributes meaning with no redundancy. It is efficiently sized for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters (2 required) and no output schema, the description is too brief. It does not explain what the output file contains, the return value format, error conditions, or that the original file is preserved. The context is incomplete for an agent to fully understand the tool's behavior and expected results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents each parameter. The description adds minimal extra meaning beyond the schema, such as the option to re-encode, but this is already implied by the codec parameter description. With high coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Extract the audio stream') and the resource ('from a video/audio file'). It also mentions the re-encoding capability, which distinguishes it from sibling tools like ffkit_add_subtitles or ffkit_clip that serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus alternatives (e.g., ffkit_transcode). It lacks explicit when-to-use or when-not-to-use conditions, and does not mention any prerequisites or context that would help an agent decide between this and sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Concatenate multiple media files into one. Use concat_demuxer (fast, same codec) or concat_filter (re-encodes, cross-format).
| Name | Required | Description | Default |
|---|---|---|---|
| method | No | Merge strategy. Default: concat_demuxer. | |
| input_paths | Yes | Ordered list of file paths to concatenate. | |
| output_path | Yes | Destination path for the merged file. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully carries the burden of behavioral disclosure. It states that the tool concatenates media files, explains two merge strategies (fast vs re-encodes), and implies the output is a single file. This is clear and sufficient for a straightforward tool with no destructive or auth concerns. No contradictions exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero wasted words. Each sentence earns its place: the first states the purpose, the second gives usage guidance. The structure is front-loaded with the action first, followed by method-specific details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and simple parameters, the description adequately covers what the tool does and how to choose the method. It could be slightly more complete by mentioning the file format requirement for concat_demuxer (same codec), but the 'same codec' hint suffices. No critical gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes each parameter. The description adds value by explaining the trade-off between concat_demuxer (fast, same codec) and concat_filter (re-encodes, cross-format) – critical semantic context beyond the schema's enum labels. Input_paths and output_path are self-explanatory, so no extra detail needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Concatenate') and resource ('multiple media files') that clearly states the tool's function. It also distinguishes between two methods (concat_demuxer vs concat_filter), adding precision. Among sibling tools like ffkit_clip or ffkit_extract_audio, this description uniquely identifies merging behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use each method (same codec vs cross-format), which helps the agent choose correctly. However, it does not mention when not to use this tool versus alternatives like ffkit_clip or ffkit_transcode for related tasks (e.g., trimming or conversion).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transcode a media file to a different format, codec, or resolution. The output container is inferred from the file extension.
| Name | Required | Description | Default |
|---|---|---|---|
| crf | No | Constant Rate Factor (lower = higher quality). | |
| fps | No | Output frame rate. | |
| preset | No | Encoder preset (e.g. 'fast', 'medium', 'slow'). | |
| bitrate | No | Target bitrate (e.g. '2M', '500k'). | |
| input_path | Yes | Source file path. | |
| resolution | No | Output resolution as WxH (e.g. '1280x720'). | |
| audio_codec | No | Audio codec (e.g. 'aac', 'libopus'). | |
| output_path | Yes | Destination file path (.mp4, .webm, .mkv, etc.). | |
| video_codec | No | Video codec (e.g. 'libx264', 'libx265', 'libvpx-vp9'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided (no readOnlyHint, destructiveHint, etc.), the description carries the full burden of behavioral disclosure. It mentions that 'the output container is inferred from the file extension,' which is a useful behavioral trait. However, it does not disclose whether the operation is destructive (e.g., overwrites output), whether it requires disk space for the output, or details about error handling (e.g., what happens with invalid codecs).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence followed by a brief note about container inference. It is concise and front-loaded with the main purpose. One could argue it could be slightly longer to add usage guidelines or behavioral notes, but it is not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, 2 required) and lack of output schema or annotations, the description is adequate but not complete. It explains the core function and one important inference, but it lacks guidance on parameter relationships (e.g., interaction between bitrate and CRF) and error behavior. A more complete description would also mention typical usage patterns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning all 9 parameters have descriptions in the input schema. The description adds minimal semantics beyond the schema: it mentions that the output container is inferred from the extension, which relates to the output_path parameter. For the most part, the description does not add substantial meaning over what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Transcode a media file to a different format, codec, or resolution.' It specifies the action (transcode), the resource (media file), and the possible transformations. It also distinguishes itself from sibling tools (which focus on subtitles, clipping, audio extraction, and merging) by being the general transcoding tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for general media conversion but provides no explicit guidance on when to use this tool versus the siblings. It doesn't state prerequisites (e.g., input file must exist) or when not to use it. However, the sibling names offer some implicit differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0ffkit_add_subtitlesffkit_clipffkit_extract_audioffkit_mergeffkit_transcodeEach tool has a clearly distinct purpose: adding subtitles, clipping, extracting audio, merging, and transcoding. Even within add_subtitles, the two modes are explicitly described, leaving no ambiguity.
All tools follow a consistent pattern: the prefix 'ffkit_' followed by a verb (clip, merge, transcode) or verb_noun (add_subtitles, extract_audio). The naming is uniform and predictable.
Five tools cover the essential media operations (clipping, format conversion, audio extraction, subtitles, concatenation) without being overwhelming or too sparse. The count is well-scoped for an ffmpeg wrapper.
The tool set covers core media manipulation tasks, but lacks some common operations like media info, video-only extraction, or advanced filters. Minor gaps exist, but the main workflows are supported.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
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.
Transform video, audio and images, and generate media from prompts. FFmpeg, captions, models.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/inthepond/ff-toolkit'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
