← All guides

Video Processing with Claude Code

Connect FFmpeg Micro to Claude Code via MCP and process videos directly from your terminal. Describe what you want in plain English and Claude handles the FFmpeg options, job submission, and result retrieval automatically.

Setup

Add the MCP server to your project's .mcp.json:

{
  "mcpServers": {
    "ffmpeg-micro": {
      "type": "http",
      "url": "https://mcp.ffmpeg-micro.com"
    }
  }
}

The first time Claude Code connects, it will open a browser window for OAuth sign-in. After you approve, the token is cached and you won't be asked again.

Example prompts

  • “Crop this landscape video to a square and give me the download link”
  • “Add a text overlay saying 'Episode 12' to the top of my video”
  • “Convert this MP4 to WebM at 720p”
  • “List my recent transcode jobs and show me which ones failed”

Why use MCP instead of the REST API?

With the REST API, you write scripts to upload files, construct FFmpeg options, poll for status, and download results. With MCP, Claude Code does all of that for you. You describe the outcome and the AI agent picks the right tools, parameters, and workflow.

MCP also handles authentication via OAuth, so you never need to copy API keys into environment variables or config files.

Troubleshooting

Common problems when running FFmpeg Micro from Claude Code, and what to do about each.

No sign-in window
Sign-in happens in a browser window the first time Claude Code uses the server. If no window opens, check that the server from Setup is saved with the URL https://mcp.ffmpeg-micro.com, exactly as written there.
Request timed out
transcode_and_wait and run_blueprint_and_wait hold the request open until the job is done, and a long render can outlast a 60-second client timeout. Ask Claude Code to start the job and check on it instead: transcode_video then get_transcode, or run_blueprint then get_blueprint_run.
A file on your machine
The tools take URLs. A local file goes up first through request_upload_url and confirm_upload, which hands back the gs:// URL to use as the input.
Download link expired
Download links are signed and short-lived. Ask for a new one and Claude Code calls get_download_url again.
Job failed
Ask Claude Code what went wrong. get_transcode returns the job's error details, for example a file over your plan's size limit or an empty token balance.

Related

Start Free, No Credit Card RequiredMCP setup guide

Want to learn more about what you can build? Explore the FFmpeg API for complete documentation, code examples, and workflows.