How to Use the FFmpeg MCP Server with Claude, Cursor, and Windsurf

Originally published at ffmpeg-micro.com.

Most FFmpeg MCP servers require you to install FFmpeg locally, manage binaries, and deal with codec dependencies. The FFmpeg Micro MCP server skips all of that. It connects your AI tool directly to a cloud video processing API. You describe what you want in plain English, and the AI handles the rest.

This guide shows you how to set it up in Claude Code, Claude Desktop, Cursor, or Windsurf, and walks through real examples you can run today.

What the FFmpeg Micro MCP Server Does

The FFmpeg Micro MCP server is a thin wrapper around the FFmpeg Micro REST API. It exposes six tools that your AI assistant can call:

• transcode_video creates a transcode job and returns immediately
• transcode_and_wait creates a job and polls until it finishes (one-shot convenience)
• get_transcode checks the status of a specific job
• list_transcodes lists your recent jobs with optional filters
• get_download_url generates a signed download link for a completed job
• cancel_transcode cancels a queued or in-progress job

The key difference from other FFmpeg MCP servers: there's no local FFmpeg binary. Video processing runs on FFmpeg Micro's cloud infrastructure. Your machine doesn't need FFmpeg installed, and you don't manage any servers.

Set Up in 2 Minutes

You need two things: an FFmpeg Micro account (free tier available at ffmpeg-micro.com) and an MCP-compatible AI tool.

Option 1: HTTP with OAuth (Zero Config)

This is the easiest setup. Add this to your MCP config file:

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

The first time you connect, your browser opens for OAuth sign-in. After that, the token is cached. No API key to copy-paste.

Where's the config file?

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
• Claude Code: ~/.claude.json or project-level .mcp.json
• Cursor: Settings > Cursor Settings > MCP
• Windsurf: ~/.codeium/windsurf/mcp_config.json

Option 2: stdio via npx (API Key)

If you prefer local transport or your tool doesn't support HTTP MCP yet:

{
  "mcpServers": {
    "ffmpeg-micro": {
      "command": "npx",
      "args": ["-y", "@ffmpeg-micro/mcp-server"],
      "env": {
        "FFMPEG_MICRO_API_KEY": "your_api_key_here"
      }
    }
  }
}

Requires Node.js 22.14 or later. Get your API key from the FFmpeg Micro dashboard.

Real Examples

Once connected, you just talk to your AI assistant. It picks the right MCP tools automatically.

Compress a Video to 720p

You type:

Compress this video to 720p medium quality: https://example.com/my-video.mp4

The AI calls transcode_video with:

{
  "inputs": [{ "url": "https://example.com/my-video.mp4" }],
  "outputFormat": "mp4",
  "preset": { "quality": "medium", "resolution": "720p" }
}

The API returns a job ID immediately. The AI then polls with get_transcode until the job completes, and fetches the download link with get_download_url.

A 13-second sample video processed in about 1 second with this exact call. The API returned:

{
  "id": "e643bb26-4753-4122-bd4c-ff90ccbee415",
  "status": "completed",
  "processing_time_seconds": 1,
  "duration_seconds": 13.35,
  "billable_minutes": 1
}

Convert MP4 to WebM

Convert my-video.mp4 to WebM format

The AI sends:

{
  "inputs": [{ "url": "https://example.com/my-video.mp4" }],
  "outputFormat": "webm"
}

No need to remember -c:v libvpx-vp9 -crf 30 -b:v 0. The API handles codec selection based on the output format.

Use Custom FFmpeg Flags

For full control, you can ask the AI to pass raw FFmpeg options:

Encode this video with H.265 at CRF 28, slow preset

The AI sends:

{
  "inputs": [{ "url": "https://example.com/my-video.mp4" }],
  "outputFormat": "mp4",
  "options": [
    { "option": "-c:v", "argument": "libx265" },
    { "option": "-crf", "argument": "28" },
    { "option": "-preset", "argument": "slow" }
  ]
}

The options array maps directly to FFmpeg flags. You get the full FFmpeg surface area without memorizing the syntax.

Batch Processing

Convert all three of these videos to 1080p MP4: video1.mp4, video2.mp4, video3.mp4

The AI can call transcode_video for each input, or use the multi-input feature to stitch them:

{
  "inputs": [
    { "url": "https://example.com/video1.mp4" },
    { "url": "https://example.com/video2.mp4" },
    { "url": "https://example.com/video3.mp4" }
  ],
  "outputFormat": "mp4",
  "preset": { "quality": "high", "resolution": "1080p" }
}

Multiple inputs get concatenated into a single output. For separate outputs, the AI makes three individual calls. Either way, you don't write any of it.

Common Pitfalls

"MCP server not found" after config change. Claude Desktop requires a full restart (not just closing the window) to pick up config changes. Cursor and Windsurf detect changes automatically.

OAuth popup doesn't appear. Make sure your browser isn't blocking popups from mcp.ffmpeg-micro.com. Some VPNs and corporate proxies also interfere with the OAuth redirect.

"Node.js version too old" with npx. The stdio transport requires Node.js 22.14+. Run node --version to check. If you're on an older version, use the HTTP transport instead.

Job stuck in "pending" status. Jobs process asynchronously on cloud infrastructure. If a job stays pending for more than 60 seconds, check your input URL. The most common cause is an unreachable or expired presigned URL.

Presigned URLs with query parameters. If your input URL already has query parameters (like S3 presigned URLs), make sure the full URL is passed as a single string. Don't split it.

FFmpeg MCP Server vs. Local FFmpeg MCP Servers

Other FFmpeg MCP servers (like egoist/ffmpeg-mcp, bitscorp-mcp/mcp-ffmpeg, and ZizoTheDev/ffmpeg-mcp) wrap a local FFmpeg binary. They're fine for personal use on a dev machine that already has FFmpeg installed. But they come with tradeoffs:

• You need FFmpeg installed and configured locally (codec support varies by build)
• Processing runs on your machine, which means CPU load and long runtimes for big files
• No cloud scaling. A 4K video that takes 20 minutes locally might take 3 minutes on cloud infrastructure
• No job management, no download URLs, no webhook notifications

FFmpeg Micro's MCP server processes video in the cloud. Your local machine stays idle. And because it's the same API that powers production apps, you get the same reliability, scaling, and job tracking.

FAQ

Do I need FFmpeg installed locally to use this?

No. The FFmpeg Micro MCP server processes everything in the cloud. You don't need FFmpeg, any codecs, or any video libraries on your machine.

How much does it cost?

FFmpeg Micro has a free tier for getting started. Paid plans bill per minute of video processed. Check ffmpeg-micro.com/pricing for current rates.

Which AI tools support MCP?

Claude Code, Claude Desktop, Cursor, Windsurf, and VS Code (via GitHub Copilot MCP) all support MCP servers. Any tool that implements the Model Context Protocol can connect.

Can I use this in production code, or just in AI tools?

The MCP server uses the same REST API that you can call directly from any language. The MCP layer is a convenience for AI-assisted development. For production, call the API directly. The FFmpeg Micro API works from Node.js, Python, Go, Ruby, Java, PHP, or any language with HTTP support.

What video formats are supported?

Input: MP4, WebM, AVI, MOV, MKV, plus audio formats (MP3, WAV, FLAC, AAC). Output: MP4, WebM, MOV. The API handles codec detection and selection automatically.

Last verified: 2026-05-27 against FFmpeg Micro MCP server v0.1.0 and API v1.0.0