FFmpeg Helper MCP server

MCP FFmpeg Helper is a lightweight server that exposes FFmpeg's powerful video processing capabilities to AI assistants through the Model Context Protocol (MCP). It enables operations like retrieving video details, converting formats, extracting audio, creating videos from image sequences, trimming videos, adding watermarks, and more.

Installation Requirements

Prerequisites

• Node.js (v14+)
• FFmpeg (must be installed on your system and accessible via command line)

You can download FFmpeg from the FFmpeg official download page.

To verify your FFmpeg installation, run:

ffmpeg -version

Installation Options

Option 1: Using NPM Package (Recommended)

This method doesn't require cloning the repository or manually building the server:

1. Configure the MCP server in your MCP configuration file:

For Windows:

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

For macOS:

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

Option 2: Manual Installation

1. Clone or download the repository
2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Configure the MCP server in your MCP configuration file:

For Windows:

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

For macOS:

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

Note: For Windows users, the configuration file is typically located at: %APPDATA%/.codeium/windsurf/mcp_config.json

Usage Examples

Getting Video Information

In Windsurf console, enter:

Please help me check the video information for "path/to/video.mp4"

Converting Video Format

In Windsurf console, enter:

Please help me convert "path/to/input.avi" to "path/to/output.mp4"

Extracting Audio

In Windsurf console, enter:

Please help me extract audio from "path/to/video.mp4" to "path/to/audio.mp3"

Creating Video from Images

In Windsurf console, enter:

Please help me create a video at "path/to/output.mp4" from images at "path/to/images/%05d.jpg"

Trimming Video

In Windsurf console, enter:

Please help me trim "path/to/input.mp4" to "path/to/output.mp4", starting at 00:00:00 and ending at 00:01:00

Adding Watermark

In Windsurf console, enter:

Please help me add a watermark to "path/to/input.mp4" saving to "path/to/output.mp4", using "path/to/watermark.png" as the watermark, positioned at [bottom-right/top-left/center], with opacity [value between 0-1]

Trimming Audio

In Windsurf console, enter:

Please help me trim "path/to/input.mp3" to "path/to/output.mp3", starting at 00:00:10 and continuing for 30 seconds

Extracting Video Frames

In Windsurf console, enter:

Please help me extract frames from "path/to/video.mp4" to "path/to/frames" folder, using PNG format for highest quality

Available Functions

1. Get Video Information (get_video_info)

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

Parameters:

• filePath: Path to the video file

Example:

get_video_info({
  filePath: "path/to/video.mp4"
})

2. Convert Video (convert_video)

Converts a video to a different format or applies specific encoding options.

Parameters:

• inputPath: Path to the input video file
• outputPath: Path for the output video file
• options: Additional FFmpeg options (optional)

Example:

convert_video({
  inputPath: "path/to/input.avi",
  outputPath: "path/to/output.mp4",
  options: "-c:v libx264 -crf 23 -preset medium"
})

3. Extract Audio (extract_audio)

Extracts audio track from a video file.

Parameters:

• inputPath: Path to the input video file
• outputPath: Path for the output audio file
• format: Audio format (e.g., mp3, aac)

Example:

extract_audio({
  inputPath: "path/to/video.mp4",
  outputPath: "path/to/audio.mp3",
  format: "mp3"
})

4. Create Video from Images (create_video_from_images)

Creates a video file from a sequence of images.

Parameters:

• inputPattern: Input image pattern (e.g., 'img%03d.jpg' or 'folder/*.png')
• outputPath: Path for the output video file
• framerate: Frame rate (default: 25)
• codec: Video codec (default: libx264)
• pixelFormat: Pixel format (default: yuv420p)
• extraOptions: Additional FFmpeg options (optional)

5. Trim Video (trim_video)

Cuts a video to a specified time segment.

Parameters:

• inputPath: Path to the input video file
• outputPath: Path for the output video file
• startTime: Start time (format: HH:MM:SS.mmm or seconds)
• duration: Duration (optional, same format as startTime)
• endTime: End time (optional, same format as startTime)

6. Add Watermark (add_watermark)

Adds an image watermark to a video.

Parameters:

• inputPath: Path to the input video file
• watermarkPath: Path to the watermark image
• outputPath: Path for the output video file
• position: Watermark position (topleft, topright, bottomleft, bottomright, center)
• opacity: Watermark opacity (0.0-1.0)

7. Trim Audio (trim_audio)

Cuts an audio file to a specified time segment.

Parameters:

• inputPath: Path to the input audio file
• outputPath: Path for the output audio file
• startTime: Start time (format: HH:MM:SS.mmm or seconds)
• duration: Duration (optional, same format as startTime)
• endTime: End time (optional, same format as startTime)
• format: Audio format (e.g., mp3, aac, optional)

8. Extract Frames (extract_frames)

Extracts frames from a video and saves them as an image sequence.

Parameters:

• inputPath: Path to the input video file
• outputDir: Directory for output images (default: 'output')
• frameRate: Frame extraction rate (e.g., '1' extracts every frame, '0.5' extracts every other frame)
• format: Output image format (jpg, png, etc., default: jpg)
• quality: Image quality (1-100, default: 95)
• startTime: Time to start extraction (optional)
• duration: Duration to extract (optional)

Troubleshooting

• Ensure FFmpeg is correctly installed and added to your system PATH
• Check that file paths are correct, especially when using backslashes (\) in Windows
• For permission issues, make sure the application has access to specified files and directories
• For complex FFmpeg commands, use the options or extraOptions parameters
• If extracted images have poor quality, try using PNG format with a higher quality value (95-99)

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.