Dynamic Media Processing: Compressing and Transcoding Streams with FFmpeg MCP

Dynamic Media Processing: Compressing and Transcoding with FFmpeg

Processing media files typically requires memorizing complex, highly-specific CLI argument strings for FFmpeg. The FFmpeg MCP server abstracts this complexity by providing a semantic boundary. Your agent can execute advanced video transcoding, audio extraction, format inspection, and scaling simply through conversational requests.

Prerequisites

1. ▸FFmpeg Installed: You must have ffmpeg and ffprobe installed on the host machine running the MCP server, and they must be accessible in your system's PATH.
2. ▸Node.js: The custom MCP bridge server requires Node.js to execute local child processes.

TypeScript Service Code

If you are writing a custom MCP server to wrap FFmpeg, you'll expose a tool that executes the binary using child processes. Here is a TypeScript blueprint:

import { exec } from 'child_process';
import util from 'util';
const execPromise = util.promisify(exec);

async function transcodeVideo(inputPath: string, outputPath: string, bitrate: string) {
  // Always use the -y flag in automated environments to avoid stalling on 'overwrite?' prompts
  const command = `ffmpeg -y -i "${inputPath}" -b:v ${bitrate} -vcodec libx264 "${outputPath}"`;
  const { stdout, stderr } = await execPromise(command);
  
  return { stdout, stderr };
}

Action Prompt Patterns

With the MCP Server running, you can give instructions like:

• ▸Batch Audio Conversion: "Convert all WAV recordings inside the /audio folder to MP3 at 192kbps, and then list the new file sizes."
• ▸Scale Video: "Create a 720p copy of my screen-recording.mov file to make it optimized for upload to Slack."
• ▸Extract Audio: "Rip the audio track from interview.mp4 and save it as a mono FLAC file."

Best Practices & Troubleshooting

• ▸Handling Large Files: Video transcoding can take minutes or hours. Because MCP is fundamentally request/response over JSON-RPC, a long-running process might timeout your AI client. It's recommended to build the FFmpeg MCP tool so it spawns the process asynchronously and returns a "job ID", allowing the agent to poll for status.
• ▸Missing Codecs: If you get a Unknown encoder error in stderr, your local installation of FFmpeg was likely compiled without support for that specific codec (e.g., missing libx264). Reinstall FFmpeg with the necessary flags.
• ▸Always Include -y: When generating FFmpeg commands, ensure your agent includes the -y flag. Otherwise, FFmpeg will hang forever in the background waiting for a Y/N keyboard input to overwrite existing files!

Using with OpenAI Codex

To use this MCP server with the OpenAI Codex CLI, you can add it to your configuration using the codex mcp add command:

codex mcp add --name ffmpeg-media --command "npx @modelcontextprotocol/server-ffmpeg-media"

(Note: Depending on the server, you may need to append arguments or use --env flags for environment variables as described in the configuration section above)