home / mcp / ffmpeg mcp server

FFmpeg MCP Server

一个基于 Model Context Protocol (MCP) 的 FFmpeg 辅助工具，提供视频处理功能。

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "sworddut-mcp-ffmpeg-helper": {
      "command": "node",
      "args": [
        "path/to/mcp-ffmpeg-helper/build/index.js"
      ]
    }
  }
}

The MCP FFmpeg Helper is a lightweight server that exposes FFmpeg’s powerful video processing capabilities through the MCP protocol. You can use it to inspect, convert, extract, and compose video and audio workflows directly from your MCP-enabled assistant.

How to use

You interact with the server through your MCP client. Define the actions you want to perform (for example, getting video details, converting formats, extracting audio, or creating a video from images) and send them to the MCP FFmpeg Helper. The server will run FFmpeg commands under the hood and return the results. You can chain multiple operations in a workflow to automate common media processing tasks without leaving your MCP environment.

Typical workflows you can implement include: getting video metadata, converting video formats, extracting audio tracks, building videos from image sequences, trimming both video and audio, adding watermarks, and exporting frames from videos.

How to install

Prerequisites you need on your system to run the MCP FFmpeg Helper:

Node.js 14+
FFmpeg installed and accessible from the command line

How to install

Step 1: Prepare your environment by installing Node.js and FFmpeg.

Step 2: Install dependencies and build (choose one installation path):

npm install
npm run build

How to install

Step 3: Configure MCP in your client for local or package-based usage.

Option A: Local Node server (manual build path) on Windows or macOS.

Windows
{
  "mcp-ffmpeg-helper": {
    "command": "cmd",
    "args": [
      "/c",
      "node",
      "path/to/mcp-ffmpeg-helper/build/index.js"
    ]
  }
}

How to install

Option B: Use the npm package directly with npx (recommended; no local build required).

Windows
{
  "mcp-ffmpeg-helper": {
    "command": "cmd",
    "args": [
      "/c",
      "npx",
      "@sworddut/mcp-ffmpeg-helper"
    ]
  }
}

How to install

macOS:
Configure to run the local node server or use npx as shown for Windows (adjust path/commands as appropriate for your environment).

macOS
{
  "mcp-ffmpeg-helper": {
    "command": "node",
    "args": [
      "path/to/mcp-ffmpeg-helper/build/index.js"
    ]
  }
}

How to install

Option B for macOS: run via npm package with npx (no build step required).

macOS
{
  "mcp-ffmpeg-helper": {
    "command": "npx",
    "args": [
      "@sworddut/mcp-ffmpeg-helper"
    ]
  }
}

Additional notes

If you need to pass extra FFmpeg options, you can provide them via the options field in the MCP call or by extending your MCP configuration to include additional command-line arguments.

Troubleshooting

Ensure FFmpeg is installed and accessible in your system PATH.
Verify file paths are correct, especially on Windows where backslashes may appear in paths.
If you encounter permission issues, ensure the MCP client and helper have the necessary access rights.
For complex FFmpeg commands, pass extra options through the options parameter.

Security and best practices

Run the MCP FFmpeg Helper with the minimum required permissions and restrict access to trusted MCP clients. Keep FFmpeg up to date and monitor resource usage when processing large media files.

Available tools

get_video_info

Retrieve detailed information about a video file, including format, codecs, resolution, and frame rate.

convert_video

Convert a video to a different format or apply encoding options.

extract_audio

Extract the audio track from a video file into a separate audio file.

create_video_from_images

Create a video from an image sequence with options for framerate, codec, and pixel format.

trim_video

Trim a video to a specified start time and duration.

add_watermark

Add an image watermark to a video at a chosen position with adjustable opacity.

trim_audio

Trim an audio file to a specified start time and duration.

extract_frames

Extract frames from a video and save them as an image sequence.