MCP FFmpeg Helper

Instructions

Implementation Reference

• src/tools/handlers.ts:107-147 (handler)

  Main execution logic for add_watermark tool: validates inputs, computes overlay position, constructs FFmpeg command with filter_complex for translucent overlay, executes via runFFmpegCommand, and returns result.

  case "add_watermark": {
    const inputPath = validatePath(String(args?.inputPath), true);
    const watermarkPath = validatePath(String(args?.watermarkPath), true);
    const outputPath = validatePath(String(args?.outputPath));
    const position = String(args?.position || "bottomright");
    const opacity = Number(args?.opacity || 0.5);
    
    await ensureDirectoryExists(outputPath);
    
    // Determine overlay position
    let overlayPosition = "";
    switch (position.toLowerCase()) {
      case "topleft":
        overlayPosition = "10:10";
        break;
      case "topright":
        overlayPosition = "W-w-10:10";
        break;
      case "bottomleft":
        overlayPosition = "10:H-h-10";
        break;
      case "center":
        overlayPosition = "(W-w)/2:(H-h)/2";
        break;
      case "bottomright":
      default:
        overlayPosition = "W-w-10:H-h-10";
        break;
    }
    
    // Improved command with better handling of watermark opacity and format
    const command = `-i "${inputPath}" -i "${watermarkPath}" -filter_complex "[1:v]format=rgba,colorchannelmixer=aa=${opacity}[watermark];[0:v][watermark]overlay=${overlayPosition}:format=auto,format=yuv420p" -codec:a copy "${outputPath}" -y`;
    const result = await runFFmpegCommand(command);
    
    return {
      content: [{
        type: "text",
        text: `Watermark added: ${inputPath} → ${outputPath}\n\n${result}`
      }]
    };
  }

• src/tools/definitions.ts:128-157 (schema)

  JSON schema defining inputs for add_watermark tool, including required paths and optional position/opacity.

  {
    name: "add_watermark",
    description: "Add a watermark to a video",
    inputSchema: {
      type: "object",
      properties: {
        inputPath: {
          type: "string",
          description: "Path to the input video file"
        },
        watermarkPath: {
          type: "string",
          description: "Path to the watermark image"
        },
        outputPath: {
          type: "string",
          description: "Path for the output video file"
        },
        position: {
          type: "string",
          description: "Position of watermark (topleft, topright, bottomleft, bottomright, center)"
        },
        opacity: {
          type: "number",
          description: "Opacity of watermark (0.0-1.0)"
        }
      },
      required: ["inputPath", "watermarkPath", "outputPath"]
    }
  },

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

  MCP server registration for listing tools; returns toolDefinitions array which includes the add_watermark tool schema.

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

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

  MCP server registration for tool calls; dispatches to handleToolCall which routes 'add_watermark' to its specific case handler.

  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}`
        }]
      };
    }
  });