How to Give Claude FFmpeg with an MCP Server

To give Claude FFmpeg, connect it to the Xora MCP server at https://api.xora.sh/v1/mcp. Claude then writes the FFmpeg arguments, sends them as a create_job tool call, and gets back a signed URL for the finished file.

This guide covers Claude Code, claude.ai and Claude Desktop. It takes one API key (or one sign-in) and no local FFmpeg install. For other agents, see FFmpeg for AI agents.

Why Claude needs a place to run FFmpeg

Claude is good at FFmpeg. Ask for “a 720p MP4 with the audio untouched” and it writes -vf scale=-2:720 -c:a copy without help. But a command is not a file. In a chat, Claude has nowhere to run it. In Claude Code, it can run FFmpeg only if FFmpeg is installed, the input is on your disk, and you are fine with your laptop doing the encode.

An MCP server fixes that step. Claude keeps writing the command; the server runs it somewhere else and reports back.

What the Xora MCP server gives Claude

The server has five tools. They call the same job routes as the REST API, so plan limits, billing and errors are the same for both.

Tool	What Claude uses it for
`list_recipes`	Read the recipe catalog once: names, parameters and output formats.
`create_job`	Start a job: a recipe, raw FFmpeg args, or a probe. Returns `{ id, state }`.
`get_job`	Poll the job. A completed job includes signed download URLs.
`create_upload`	Get a presigned URL for a local file that has no public address.
`cancel_job`	Stop a queued or running job.

Step 1: Get an API key

If you only use claude.ai or Claude Desktop, you can skip the key: those clients sign in to Xora with OAuth (see step 2b).

Step 2a: Connect Claude Code

Run this in your terminal:

claude mcp add --transport http xora https://api.xora.sh/v1/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Then start Claude Code and type /mcp. The xora server shows as connected, with its five tools.

To check the connection without Claude, list the tools with the MCP Inspector:

npx @modelcontextprotocol/inspector --cli https://api.xora.sh/v1/mcp \
  --transport http \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --method tools/list

Step 2b: Connect claude.ai or Claude Desktop

Open Settings → Connectors → Add custom connector.
Paste https://api.xora.sh/v1/mcp.
Sign in to your Xora account and approve the access prompt.

There is no key to copy. To remove access later, use the dashboard link on the consent screen.

Step 3 (optional): Add the Xora skill

The MCP tools tell Claude what it can call. The Xora skill tells it how to use them well: which recipe fits which ask, when to probe first, and cost habits such as stageInput: false for thumbnails. For Claude Code:

mkdir -p ~/.claude/skills/xora && \
  curl -fsSL https://xora.sh/skills/xora/SKILL.md -o ~/.claude/skills/xora/SKILL.md

In claude.ai, upload the same file as a custom skill.

Step 4: Ask Claude for a video job

Give Claude a public URL and say what you want:

Make a smaller MP4 of https://example.com/interview.mov for the web. Keep it 1080p.

Claude reads the recipe catalog and picks compress. The tool call looks like this:

{
  "mode": "recipe",
  "input": { "url": "https://example.com/interview.mov" },
  "output": { "format": "mp4" },
  "recipe": { "name": "compress", "crf": 23 },
  "idempotencyKey": "interview-compress-crf23"
}

The server replies at once with { "id": "01JXYZ…", "state": "queued" }. Claude polls get_job until the state is completed, failed, rejected or cancelled. A completed job has the download link:

{
  "id": "01JXYZ1234ABCDEF56789000",
  "state": "completed",
  "progress": 100,
  "output": { "signedUrl": "https://cdn.xora.sh/...signed-url..." }
}

Signed URLs expire, so download the file when Claude gives you the link.

When a recipe is not enough: raw FFmpeg args

For anything a recipe does not cover, Claude switches to mode: "ffmpeg" and sends the arguments it would run locally. This prompt:

Put logo.png in the bottom-right corner of talk.mp4 and keep the original audio.

becomes this tool call:

{
  "mode": "ffmpeg",
  "input_files": {
    "in_1": "https://example.com/talk.mp4",
    "in_2": "https://example.com/logo.png"
  },
  "output_files": { "out_1": "talk_branded.mp4" },
  "ffmpeg": {
    "args": [
      "-i", "{{in_1}}",
      "-i", "{{in_2}}",
      "-filter_complex", "[0:v][1:v]overlay=W-w-24:H-h-24",
      "-c:v", "libx264", "-crf", "23",
      "-c:a", "copy",
      "{{out_1}}"
    ]
  }
}

{{in_1}} and {{out_1}} are placeholders that Xora replaces with real paths. Output file names use letters, numbers and underscores, plus the extension. Each array element goes to FFmpeg as one argument, so there is no shell quoting to get wrong. See custom FFmpeg args for the full rules.

Files on your computer

If the video is on your disk, Claude Code can upload it:

Claude calls create_upload with the file size and name.
It sends the file with one PUT to the returned URL (no auth header, valid for one hour).
It calls create_job with "input": { "uploadId": "…" } in place of a URL.

The upload stays for three days, so Claude can run several jobs on it without a second upload. In claude.ai, give Claude a URL: a public link, or a presigned link to your own bucket.

When something goes wrong

Tool errors come back as JSON with a code, so Claude can tell you what happened in plain words:

`error.code`	What it means
`VALIDATION_ERROR`	The request is wrong. Claude can read the message and fix the field.
`LIMIT_EXCEEDED`	The plan’s credits or storage are used up.
`PLAN_REQUIRED`	The feature, for example delivery to your own R2 bucket, is not on your plan.
`NOT_FOUND`	No job with that id on this account.

A job that fails or is rejected costs nothing. More detail is in the MCP server docs and the error handling guide.

Next steps

Using Cursor? See Run FFmpeg Jobs from Cursor with MCP.
See every way an agent can reach Xora on FFmpeg for AI agents.
Read the recipe docs to see what each recipe accepts.

Frequently asked questions

Can Claude run FFmpeg?

Claude can write FFmpeg commands, but it needs a tool to run them. With the Xora MCP server connected, Claude sends the FFmpeg arguments as a create_job tool call, Xora runs the job in the cloud, and Claude gets a signed URL for the output.

Do I need FFmpeg installed on my computer?

No. FFmpeg runs on Xora. Your computer only sends the job, and for local files, one HTTP PUT to upload the input.

Does the MCP server work in claude.ai, or only in Claude Code?

Both. In Claude Code you add the server with one claude mcp add command and an API key. In claude.ai and Claude Desktop you add https://api.xora.sh/v1/mcp as a custom connector and sign in to your Xora account.

What does a job cost when Claude runs it?

The same as a REST job: credits for machine time and output size. Failed, rejected and cancelled jobs cost nothing, so a wrong command from Claude does not cost you credits.