MCP FFmpeg Helper

Instructions

Implementation Reference

• src/tools/handlers.ts:188-240 (handler)

  The switch case in handleToolCall that implements the extract_frames tool. It validates input, constructs an FFmpeg command to extract frames at specified rate/format/quality, ensures output directory exists, runs the command, and returns success message with result.
  case "extract_frames": { const inputPath = validatePath(String(args?.inputPath), true); const outputDir = String(args?.outputDir || "output"); const frameRate = String(args?.frameRate || "1"); const format = String(args?.format || "jpg"); const quality = Number(args?.quality || 95); const startTime = args?.startTime ? String(args?.startTime) : ""; const duration = args?.duration ? String(args?.duration) : ""; // Create output directory if it doesn't exist await ensureDirectoryExists(join(outputDir, "dummy.txt")); // Build the FFmpeg command let command = `-i "${inputPath}"`; // Add start time if provided if (startTime) { command += ` -ss ${startTime}`; } // Add duration if provided if (duration) { command += ` -t ${duration}`; } // Set frame extraction rate command += ` -vf "fps=${frameRate}"`; // Set quality based on format if (format.toLowerCase() === "jpg" || format.toLowerCase() === "jpeg") { // For JPEG, use a better quality setting (lower values = higher quality in FFmpeg's scale) // Convert 1-100 scale to FFmpeg's 1-31 scale (inverted, where 1 is best quality) const ffmpegQuality = Math.max(1, Math.min(31, Math.round(31 - ((quality / 100) * 30)))); command += ` -q:v ${ffmpegQuality}`; } else if (format.toLowerCase() === "png") { // For PNG, use compression level (0-9, where 0 is no compression) const compressionLevel = Math.min(9, Math.max(0, Math.round(9 - ((quality / 100) * 9)))); command += ` -compression_level ${compressionLevel}`; } // Set output pattern with 5-digit numbering const outputPattern = join(outputDir, `%05d.${format}`); command += ` "${outputPattern}" -y`; const result = await runFFmpegCommand(command); return { content: [{ type: "text", text: `Frames extracted from video: ${inputPath} → ${outputDir}/*.${format}\n\n${result}` }] }; }
• src/tools/definitions.ts:192-229 (schema)

  The input schema and metadata definition for the 'extract_frames' tool within the toolDefinitions array.
  { name: "extract_frames", description: "Extract frames from a video as sequential image files", inputSchema: { type: "object", properties: { inputPath: { type: "string", description: "Path to the input video file" }, outputDir: { type: "string", description: "Directory to save the extracted frames (default: 'output')" }, frameRate: { type: "string", description: "Frame extraction rate (e.g., '1' for every frame, '0.5' for every 2nd frame, '1/30' for 1 frame per 30 seconds)" }, format: { type: "string", description: "Output image format (jpg, png, etc., default: jpg)" }, quality: { type: "number", description: "Image quality for jpg format (1-100, default: 95)" }, startTime: { type: "string", description: "Start time to begin extraction (format: HH:MM:SS.mmm or seconds)" }, duration: { type: "string", description: "Duration to extract frames (format: HH:MM:SS.mmm or seconds)" } }, required: ["inputPath"] } }
• src/index.ts:46-50 (registration)

  Registration of the list tools handler that exposes all tool definitions, including 'extract_frames', via toolDefinitions.
  server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: toolDefinitions }; });
• src/index.ts:56-58 (registration)

  Registration of the call tool handler that dispatches to handleToolCall, which implements the 'extract_frames' logic.
  server.setRequestHandler(CallToolRequestSchema, async (request) => { try { return await handleToolCall(request.params.name, request.params.arguments);
• src/tools/handlers.ts:1-23 (helper)

  Imports of helper functions used in the extract_frames handler: validatePath and ensureDirectoryExists from file.ts, runFFmpegCommand from ffmpeg.ts.
  import { validatePath } from "../utils/file.js"; import { getVideoInfo, runFFmpegCommand } from "../utils/ffmpeg.js"; import { ensureDirectoryExists } from "../utils/file.js"; import { join } from "path"; /** * Handles all FFmpeg tool requests */ export async function handleToolCall(toolName: string, args: any) { switch (toolName) { case "get_video_info": { const filePath = validatePath(String(args?.filePath), true); const info = await getVideoInfo(filePath); return { content: [{ type: "text", text: info }] }; } case "convert_video": { const inputPath = validatePath(String(args?.inputPath), true);