FFmpeg Media Processing MCP Guide

sudo apt-get update && sudo apt-get install -y ffmpeg

brew install ffmpeg

{
  "mcpServers": {
    "ffmpeg-media": {
      "command": "node",
      "args": ["/opt/mcp-servers/ffmpeg/dist/index.js"],
      "env": {
        "TEMP_MEDIA_DIR": "/tmp/mcp-transcoding",
        "MAX_CONCURRENT_JOBS": "2"
      }
    }
  }
}

{
  "mcpServers": {
    "ffmpeg-media": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "TEMP_MEDIA_DIR": "./.temp-media"
      }
    }
  }
}

[mcp_servers.ffmpeg_media]
command = "node"
args = ["/opt/mcp-servers/ffmpeg/dist/index.js"]

[mcp_servers.ffmpeg_media.env]
TEMP_MEDIA_DIR = "/tmp/mcp-transcoding"
MAX_CONCURRENT_JOBS = "2"

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import { spawn, execFile } from 'child_process';
import { promisify } from 'util';
import crypto from 'crypto';

const execFileAsync = promisify(execFile);

interface TranscodeJob {
  id: string;
  inputPath: string;
  outputPath: string;
  status: 'processing' | 'completed' | 'failed';
  error?: string;
  startedAt: number;
}

const jobs = new Map<string, TranscodeJob>();

const server = new Server(
  { name: 'ffmpeg-media-mcp', version: '1.0.0' },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: 'probe_media_metadata',
        description: 'Inspect media file format, duration, codecs, resolution, and audio channels using ffprobe.',
        inputSchema: {
          type: 'object',
          properties: {
            file_path: { type: 'string', description: 'Absolute path to media file' }
          },
          required: ['file_path']
        }
      },
      {
        name: 'transcode_media_async',
        description: 'Start an asynchronous video or audio transcoding job.',
        inputSchema: {
          type: 'object',
          properties: {
            input_path: { type: 'string', description: 'Source media file path' },
            output_path: { type: 'string', description: 'Destination media file path' },
            preset: { 
              type: 'string', 
              enum: ['mp4_720p', 'mp4_1080p', 'extract_audio_mp3', 'extract_audio_wav'],
              description: 'Target encoding preset'
            }
          },
          required: ['input_path', 'output_path', 'preset']
        }
      },
      {
        name: 'check_transcode_status',
        description: 'Check the status of an ongoing or completed transcode job by job ID.',
        inputSchema: {
          type: 'object',
          properties: {
            job_id: { type: 'string', description: 'Job ticket identifier' }
          },
          required: ['job_id']
        }
      }
    ]
  };
});

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  try {
    if (name === 'probe_media_metadata') {
      const filePath = args?.file_path as string;
      const { stdout } = await execFileAsync('ffprobe', [
        '-v', 'quiet',
        '-print_format', 'json',
        '-show_format',
        '-show_streams',
        filePath
      ]);

      const parsed = JSON.parse(stdout);
      return {
        content: [{ type: 'text', text: JSON.stringify(parsed, null, 2) }]
      };
    }

    if (name === 'transcode_media_async') {
      const inputPath = args?.input_path as string;
      const outputPath = args?.output_path as string;
      const preset = args?.preset as string;

      const jobId = 'job_' + crypto.randomBytes(4).toString('hex');
      const job: TranscodeJob = {
        id: jobId,
        inputPath,
        outputPath,
        status: 'processing',
        startedAt: Date.now()
      };
      jobs.set(jobId, job);

      let ffmpegArgs: string[] = ['-nostdin', '-y', '-i', inputPath];

      if (preset === 'mp4_720p') {
        ffmpegArgs.push('-vf', 'scale=-2:720', '-c:v', 'libx264', '-crf', '23', '-c:a', 'aac', outputPath);
      } else if (preset === 'mp4_1080p') {
        ffmpegArgs.push('-vf', 'scale=-2:1080', '-c:v', 'libx264', '-crf', '21', '-c:a', 'aac', outputPath);
      } else if (preset === 'extract_audio_mp3') {
        ffmpegArgs.push('-vn', '-c:a', 'libmp3lame', '-b:a', '192k', outputPath);
      } else if (preset === 'extract_audio_wav') {
        ffmpegArgs.push('-vn', '-c:a', 'pcm_s16le', outputPath);
      }

      const proc = spawn('ffmpeg', ffmpegArgs, { stdio: ['ignore', 'ignore', 'pipe'] });

      let stderrOutput = '';
      proc.stderr.on('data', chunk => { stderrOutput += chunk.toString(); });

      proc.on('close', code => {
        if (code === 0) {
          job.status = 'completed';
        } else {
          job.status = 'failed';
          job.error = stderrOutput.slice(-300);
        }
      });

      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              message: 'Transcode task queued successfully.',
              job_id: jobId,
              status: 'processing',
              output_path: outputPath
            }, null, 2)
          }
        ]
      };
    }

    if (name === 'check_transcode_status') {
      const jobId = args?.job_id as string;
      const job = jobs.get(jobId);

      if (!job) {
        return { isError: true, content: [{ type: 'text', text: `Job ID '${jobId}' not found.` }] };
      }

      return {
        content: [{ type: 'text', text: JSON.stringify(job, null, 2) }]
      };
    }

    throw new Error(`Unrecognized tool: ${name}`);
  } catch (err: any) {
    return {
      isError: true,
      content: [{ type: 'text', text: `FFmpeg Operation Failed: ${err.message}` }]
    };
  }
});

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch((err) => {
  process.stderr.write(`Fatal server error: ${err.message}\n`);
  process.exit(1);
});

{
  "jsonrpc": "2.0",
  "id": "media-job-01",
  "method": "tools/call",
  "params": {
    "name": "transcode_media_async",
    "arguments": {
      "input_path": "/workspace/recordings/demo.mov",
      "output_path": "/workspace/dist/demo_720p.mp4",
      "preset": "mp4_720p"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": "media-job-01",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"message\": \"Transcode task queued successfully.\",\n  \"job_id\": \"job_e4a819b2\",\n  \"status\": \"processing\",\n  \"output_path\": \"/workspace/dist/demo_720p.mp4\"\n}"
      }
    ]
  }
}