FFmpeg API for Claude Code: Build an MCP Conversion Tool

TL;DR: - FFmpeg has no official REST API — "the FFmpeg API" almost always means either its C libraries (libavcodec/libavformat) or a hosted wrapper like Convert Fleet or fal.ai's ffmpeg-api that exposes conversion over HTTP. - Letting an AI agent shell out to a local ffmpeg binary is fragile: path issues, missing codecs, and runaway processes with no timeout. - Wrapping a hosted FFmpeg API as a single-purpose MCP server gives Claude Code one clean convert_file tool instead of raw shell access — safer, and easier to reason about. - The July 2026 MCP ecosystem push favors scoped, production-grade servers over do-everything ones; most builders now cap their active MCP toolset at 3-6 servers. - A ready-to-import MCP server template is in the free download below, so you can skip the boilerplate.

Your agent needs to convert a video, and you're staring at two bad options: shell out to a local ffmpeg binary and pray the container has the right codecs installed, or hand-roll yet another HTTP client. Neither scales past a demo.

This is the actual gap developers hit when they search for an ffmpeg api: FFmpeg itself ships no such thing. What you want is a small, scoped tool that Claude Code (or any MCP client) can call — one function, convert_file, that takes a file and a target format and comes back with a result. No shell access, no timeout surprises, no "works on my machine."

This guide builds that tool. We'll cover what the FFmpeg API actually is, why wrapping it in MCP beats shelling out, working code in six languages, how it plugs into n8n and Make.com, and the mistakes that eat an afternoon if you skip them.

Does FFmpeg Have an API? What "FFmpeg API" Actually Means

FFmpeg does not ship an official REST or cloud API — it's a command-line tool and a set of C libraries (libavcodec, libavformat, libavfilter) that you either call from the terminal or link into your own program. When people search "ffmpeg api" they usually mean one of three different things, and mixing them up is where most confusion starts.

The three real answers:

1. The FFmpeg C libraries — libavcodec and friends, used when you're building a native app in C or C++ and need frame-level control (this is the true "ffmpeg c api").
2. A local CLI wrapper — your own script that calls the ffmpeg binary from Python, Node, PHP, or Java and parses stdout. Still requires FFmpeg installed on that machine.
3. A hosted FFmpeg REST API — a service like Convert Fleet or fal.ai's ffmpeg-api that runs FFmpeg on its own servers and gives you an HTTP endpoint. You send a file or URL, you get back a converted file. No installation, no binary to manage.

For an AI agent, option three is almost always the right call. An agent shouldn't need shell access to convert a file — it needs a tool with a schema, a timeout, and a predictable response. That's exactly what a hosted API plus an MCP wrapper gives you.

Can I Use FFmpeg Without Installing It Locally?

Yes. Hosted FFmpeg REST APIs run the conversion on their own infrastructure and return the result over HTTP, so your server, container, or CI runner never needs the ffmpeg binary at all. You send a request; you get a file URL or byte stream back.

This matters more than it sounds like at first. FFmpeg's build matrix is genuinely messy — different platforms ship with different codec libraries compiled in (some builds lack H.265 or AAC encoding for licensing reasons), and a script that works on your laptop can fail silently in a Docker image that has a stripped-down FFmpeg build. Teams running agents in ephemeral containers (Lambda, Vercel functions, serverless workers) hit this constantly, because rebuilding a full FFmpeg binary into a cold-start function adds real weight and boot time.

A hosted API sidesteps all of it: the conversion happens somewhere with FFmpeg already correctly configured, and your code just makes an HTTP call. This is also the cleanest path for AI agents specifically, since the agent's runtime (a Claude Code session, a serverless MCP host) usually isn't a place you want to install and maintain system binaries anyway.

Why Wrap It as an MCP Server for Claude Code

An MCP server is a small program that exposes a defined set of tools to an AI client over a standard protocol — Anthropic introduced the Model Context Protocol in November 2024, and by mid-2026 it's become the default way Claude Code, Cursor, and other agent runtimes connect to external capabilities. Instead of an agent improvising shell commands, it calls a named tool with a typed schema.

Here's the part most MCP tutorials skip: scope matters more than capability. A general "run any ffmpeg command" tool sounds flexible, but it hands the model shell-level power over your file system and CPU — a bad idea the moment the agent is processing untrusted input. A scoped convert_file tool, by contrast, only ever does one thing: takes a source, a target format, maybe a few named options (resolution, bitrate, watermark), and returns a result. The model can't ask it to do anything else because the tool doesn't expose anything else.

This scoped approach is also where the ecosystem is heading. The July 2026 wave of MCP tooling leans hard into single-purpose, production-grade servers over sprawling all-in-one ones — and most builders curating their agent's toolset now keep it to roughly 3-6 active MCP servers at a time, because every extra server is more context spent on tool descriptions and more surface area for the model to pick the wrong one. A tight convert_file server earns its slot; a bloated "media-tools-mega-server" doesn't.

If you want the fuller architecture picture — multiple file-format tools, not just conversion — see our walkthrough on building a file conversion MCP server for Claude.

Local FFmpeg vs Hosted FFmpeg API vs MCP-Wrapped API

Here's the decision most developers are actually stuck on: do you shell out locally, call a hosted API directly, or wrap that API as an MCP tool? The right answer depends on who — or what — is doing the calling.

If you're writing a backend service by hand, calling the hosted API directly is fine. If an AI agent is the one making the call, the MCP wrapper is worth the extra 20 minutes of setup — it's the difference between a tool the model can use safely and a shell it can misuse.

How to Use an FFmpeg API: Building the convert_file MCP Tool, Step by Step

Here's the actual build, in order. This assumes you're using a hosted FFmpeg API (we'll use Convert Fleet's endpoints as the example, but the pattern holds for any REST-based conversion API).

1. Pick one scope. Decide the tool does exactly one job: convert_file(source, target_format, options). Resist the urge to also add trim_video, extract_audio, and run_arbitrary_command in the same server — split those into separate tools if you need them.
2. Choose a transport. For local Claude Code use, stdio is simplest (the server runs as a subprocess). For a shared team setup, run it as an HTTP-based MCP server behind auth.
3. Define the tool schema. Inputs: source_url or file bytes, target_format, and an optional options object (bitrate, resolution, watermark text). Keep required fields to a minimum.
4. Implement the handler to call the hosted API instead of spawning a process — this is the step that removes the "do I need ffmpeg installed locally" problem entirely.
5. Set an explicit timeout and a retry-once policy. Video jobs run long; don't inherit whatever default your HTTP client ships with.
6. Store the API key in an environment variable, never hardcoded in the server file you might commit.
7. Register the server in Claude Code's MCP config (mcp.json or via claude mcp add).
8. Test with one real file end-to-end before trusting the agent with it — convert something small first.
9. Grab the ready-made server in the free download below instead of typing all of this from scratch — it ships with steps 1-7 already wired up.

Minimal Node.js MCP server implementing that convert_file tool:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({ name: "ffmpeg-convert", version: "1.0.0" });

server.setRequestHandler("tools/call", async (req) => {
  if (req.params.name !== "convert_file") throw new Error("Unknown tool");
  const { source_url, target_format } = req.params.arguments;

  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), 60_000); // hard 60s ceiling

  try {
    const res = await fetch("https://api.convertfleet.com/v1/convert", {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.CONVERTFLEET_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ source_url, target_format }),
      signal: controller.signal,
    });
    if (!res.ok) throw new Error(`Conversion failed: ${res.status}`);
    return { content: [{ type: "text", text: JSON.stringify(await res.json()) }] };
  } finally {
    clearTimeout(timeout);
  }
});

new StdioServerTransport().connect(server);

Register it for Claude Code with a config entry like:

{
  "mcpServers": {
    "ffmpeg-convert": {
      "command": "node",
      "args": ["./ffmpeg-mcp-server.js"],
      "env": { "CONVERTFLEET_API_KEY": "YOUR_API_KEY" }
    }
  }
}

That's the whole shape. Everything after this is language choice and polish — see our MCP file converter walkthrough for Claude and Cursor if you want the multi-tool version.

FFmpeg API Examples in Python, PHP, C#, Java, and REST

Whatever language sits behind your MCP server (or your regular backend), the underlying call is the same: POST a source and a target format, get a job or file back. Here's the pattern across the languages developers actually ask about.

FFmpeg Python API (calling a hosted REST endpoint, not the CLI):

import requests

resp = requests.post(
    "https://api.convertfleet.com/v1/convert",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"source_url": "https://example.com/input.mov", "target_format": "mp4"},
    timeout=60,
)
resp.raise_for_status()
print(resp.json()["output_url"])

FFmpeg PHP API:

$ch = curl_init("https://api.convertfleet.com/v1/convert");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_API_KEY", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode(["source_url" => $url, "target_format" => "mp4"]),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
]);
$result = json_decode(curl_exec($ch), true);

FFmpeg API C#:

using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
client.DefaultRequestHeaders.Authorization = new("Bearer", "YOUR_API_KEY");
var response = await client.PostAsJsonAsync(
    "https://api.convertfleet.com/v1/convert",
    new { source_url = sourceUrl, target_format = "mp4" });

FFmpeg Java API:

HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(60)).build();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.convertfleet.com/v1/convert"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .POST(HttpRequest.BodyPublishers.ofString(payloadJson))
    .build();

Note the pattern repeating across all four: auth header, JSON body, explicit timeout. That third one is easy to skip and the one that bites hardest in production — more on that below. If you're weighing this hosted approach against learning raw FFmpeg first, our plain-language FFmpeg primer covers the CLI fundamentals these APIs are abstracting away.

For more advanced hosted operations — compositing multiple tracks, applying keyframe-based edits, layering an image overlay or watermark — services like fal.ai's ffmpeg-api expose those as dedicated endpoints rather than raw command strings, which is worth knowing if your use case goes beyond simple format conversion.

Integrating FFmpeg Conversion with n8n and Make.com

Not every team wants a Claude Code MCP server — plenty are automating conversions through n8n or Make.com instead, and the underlying problem is identical: don't shell out, call a hosted API node.

In n8n, the cleanest setup is an HTTP Request node pointed at your FFmpeg API's /convert endpoint, with the source file passed as a URL from a prior node (Google Drive, S3, a webhook trigger) and the response's output_url fed into whatever comes next — an email, a storage upload, a Slack message. You don't need FFmpeg installed on your n8n instance at all, which matters if you're running n8n on a lightweight VPS or a managed cloud plan without a full media stack.

In Make.com, the equivalent is an HTTP module (or a custom app if one exists for your provider) making the same POST request, with the scenario's error-handling route catching non-200 responses so a failed conversion doesn't silently break the rest of the automation.

Both platforms hit the same failure mode if you skip timeout handling: a conversion that takes longer than the platform's own HTTP timeout looks like a crash, not a slow job. Grab the ready-made workflow in the free download below — it's a pre-built n8n import that handles the request, the timeout, and the error branch, so you're not reconstructing this from three different forum posts. For the fuller Google Drive-triggered version, see our n8n file conversion workflow guide.

Common Mistakes When Building an FFmpeg API Tool

Most of these show up the first time a conversion job takes longer than expected, not during initial testing — which is exactly why they're worth checking before you ship, not after.

• No explicit timeout. Serverless platforms cap function execution hard — AWS Lambda tops out at 15 minutes but defaults to just 3 seconds, and Vercel's free-tier functions default to 10 seconds. A large video conversion will blow past both if you haven't explicitly raised the ceiling or moved the job to a queue.
• Treating a timeout as a conversion failure. A 504 often just means "still processing," not "broken." Poll a job-status endpoint instead of assuming a timeout equals an error.
• Giving the agent raw shell access instead of a scoped tool. This is the mistake the whole MCP-wrapper approach exists to prevent — don't undo it by adding a generic "run command" fallback tool next to convert_file.
• Hardcoding the API key in the server file. Use an environment variable; a committed key in a public MCP server template is a real, common leak vector.
• Skipping format validation before the request. Sending an unsupported target format wastes a full round trip; validate against a known list client-side first.
• Assuming FFmpeg is installed wherever the code runs. It usually isn't in a fresh container — that's the whole reason the hosted-API approach exists.
• Registering too many MCP servers at once. Beyond the 3-6 active servers most builders settle on, Claude Code spends more context deciding which tool to call than it saves you in capability.

Is FFmpeg Free? Licensing for Commercial Projects

FFmpeg itself is free and open source under the LGPL (or GPL, depending on which optional components are compiled in) — you can use it commercially without paying FFmpeg anything, though GPL-linked builds require you to comply with GPL's source-availability terms if you redistribute the binary. See the FFmpeg license page for the exact terms that apply to your build configuration.

Hosted FFmpeg APIs are a separate cost question. The software running underneath is free; what you're paying for (when you pay) is the hosting, uptime, and the engineering that turned a CLI tool into a reliable HTTP endpoint. Free tiers on hosted FFmpeg APIs typically exist for smaller volumes or personal projects, with paid tiers covering higher throughput and priority processing — check the specific provider's pricing page for current limits, since these change. Convert Fleet's own pricing page lays out what's included at each tier if you want a concrete reference point.

Free download

To make this actionable, we built a free resource you can grab right now — no signup:

• ⬇ N8N Workflow: ffmpeg-api-workflow-a25c7fe34aeaaf0e.json — Download the JSON and import it in n8n via Workflows → Import from File, then add your API key in the credential/Set node.

Frequently Asked Questions

Is there a free FFmpeg API available? Yes — several hosted providers, including Convert Fleet, offer a free tier for FFmpeg-based conversion, usually capped by file size or monthly volume. The underlying FFmpeg software is always free and open source regardless of which hosted wrapper you use.

Can I use FFmpeg without installing it on my server? Yes. A hosted FFmpeg REST API runs the conversion on the provider's infrastructure and returns the result over HTTP, so your own server, container, or serverless function never needs the FFmpeg binary installed.

Is FFmpeg free to use for commercial projects? Yes, FFmpeg is open source under LGPL/GPL and can be used commercially at no cost, though GPL-linked builds carry source-disclosure obligations if you redistribute the binary itself. Using a hosted API sidesteps this entirely since you're calling a service, not shipping FFmpeg's code.

How do I use an FFmpeg API in an AI agent? Wrap the API's endpoint as a single-purpose MCP tool (like convert_file) with a typed schema, an explicit timeout, and the API key in an environment variable, then register that server with your agent client (Claude Code, Cursor, or another MCP host).

Does FFmpeg have an official API? No — FFmpeg ships as a CLI tool and a set of C libraries, not an official REST API. "FFmpeg API" in practice refers to either those C libraries or a third-party hosted service that wraps FFmpeg behind an HTTP endpoint.

Conclusion

FFmpeg gives you the conversion engine; it was never going to give you the agent-safe interface on top. That's the part you build — and building it as one scoped convert_file MCP tool, backed by a hosted API instead of a local binary, is what turns "the agent tried to run ffmpeg and it broke" into a tool call that just works.

If you'd rather skip the boilerplate, Convert Fleet's free API tier gives you the hosted conversion endpoint this whole guide points at — grab the free MCP server download above and you'll have convert_file running in Claude Code in under ten minutes.