MCP FFmpeg Helper

Instructions

Implementation Reference

• src/tools/handlers.ts:56-78 (handler)

  The core handler logic for the 'create_video_from_images' tool. It processes input arguments, builds an FFmpeg command to generate a video from images using the specified pattern, framerate, codec, pixel format, and extra options, executes it via runFFmpegCommand, and returns the completion message with results.

  case "create_video_from_images": {
    const inputPattern = String(args?.inputPattern);
    const outputPath = validatePath(String(args?.outputPath));
    const framerate = Number(args?.framerate || 25);
    const codec = String(args?.codec || "libx264");
    const pixelFormat = String(args?.pixelFormat || "yuv420p");
    const extraOptions = String(args?.extraOptions || "");
    
    if (!inputPattern) {
      throw new Error("Input pattern is required");
    }
    
    await ensureDirectoryExists(outputPath);
    const command = `-framerate ${framerate} -i "${inputPattern}" -c:v ${codec} -pix_fmt ${pixelFormat} ${extraOptions} "${outputPath}" -y`;
    const result = await runFFmpegCommand(command);
    
    return {
      content: [{
        type: "text",
        text: `Video creation completed: ${inputPattern} → ${outputPath}\n\n${result}`
      }]
    };
  }

• src/tools/definitions.ts:64-97 (schema)

  The tool schema definition specifying name, description, and input schema with properties for inputPattern (required), outputPath (required), framerate, codec, pixelFormat, and extraOptions.

  {
    name: "create_video_from_images",
    description: "Create a video from a sequence of images",
    inputSchema: {
      type: "object",
      properties: {
        inputPattern: {
          type: "string",
          description: "Pattern for input images (e.g., 'img%03d.jpg' or 'folder/*.png')"
        },
        outputPath: {
          type: "string",
          description: "Path for the output video file"
        },
        framerate: {
          type: "number",
          description: "Frames per second (default: 25)"
        },
        codec: {
          type: "string",
          description: "Video codec to use (default: libx264)"
        },
        pixelFormat: {
          type: "string",
          description: "Pixel format (default: yuv420p)"
        },
        extraOptions: {
          type: "string",
          description: "Additional FFmpeg options"
        }
      },
      required: ["inputPattern", "outputPath"]
    }
  },

• src/index.ts:46-50 (registration)

  Registers the tool by including it in the toolDefinitions array returned for ListToolsRequestSchema, making the schema and description available to clients.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: toolDefinitions
    };
  });

• src/index.ts:56-68 (registration)

  Registers the generic tool call handler that dispatches to the specific handler in handlers.ts based on tool name, enabling execution of create_video_from_images.

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    try {
      return await handleToolCall(request.params.name, request.params.arguments);
    } catch (error: any) {
      console.error("Tool execution error:", error.message);
      return {
        content: [{
          type: "text",
          text: `Error: ${error.message}`
        }]
      };
    }
  });