FFmpeg MCP Server

MCP server providing FFmpeg video processing via base64 I/O. Stateless, portable, zero external dependencies.

Tools

get_ffmpeg_version

Returns FFmpeg version information.

resize_video

Resize video to standard resolutions (360p, 480p, 720p, 1080p). Outputs H.264/AAC.

Parameters:

• videoBase64 (string): Base64 encoded video

• resolutions (array): Target resolutions

• outputFormat (string, optional): mp4 or webm (default: mp4)

Returns: Base64 encoded video for each resolution

extract_audio

Extract audio track from video.

Parameters:

• videoBase64 (string): Base64 encoded video

• format (string): mp3, aac, wav, or ogg

Returns: Base64 encoded audio

get_video_info

Inspect video metadata: format, duration, bitrate, resolution, codecs, streams.

Parameters:

• videoBase64 (string): Base64 encoded video

Returns: Formatted metadata

Design

Base64 I/O: All inputs and outputs are base64 encoded. No file paths, S3 URLs, or database storage.

Why:

• Stateless: No persistent storage, cleanup, or orphaned files

• Portable: Works in any Node.js environment

• Simple: Single request/response cycle

Constraints:

• Payload limits: ~4-6 MB depending on runtime

• Best for: Thumbnails, previews, short clips, audio extraction

• Not for: Feature films, 4K processing

Processing flow:

1. Decode base64 input → temp file

2. Execute FFmpeg

3. Read output → buffer

4. Delete temp files

5. Encode buffer → base64

Installation

FFmpeg binaries install automatically via ffmpeg-static and @ffprobe-installer/ffprobe.

npm install @windsornguyen/ffmpeg-mcp

Configuration

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "ffmpeg": {
      "command": "npx",
      "args": ["-y", "@windsornguyen/ffmpeg-mcp"]
    }
  }
}

VS Code

.vscode/mcp.json:

{
  "servers": {
    "ffmpeg": {
      "command": "npx",
      "args": ["-y", "@windsornguyen/ffmpeg-mcp"]
    }
  }
}

Development

# Install dependencies
bun install

# Build
bun run build

# Test
bun test

# Run STDIO transport
bun run dev:stdio

# Run HTTP transport
bun run dev:shttp

Environment Variables

• PORT: HTTP server port (default: 3002)

• NODE_ENV: development | production

Testing

# Run all tests
bun test

# Run with output artifacts (kept in tests/output/)
bun test --keep-artifacts

# Single test file
bun test tests/ffmpeg.test.ts

Tests verify base64 round-trip encoding, resolution accuracy, and codec compliance. Output artifacts saved to tests/output/ when --keep-artifacts is set.

Architecture

• Client (src/client.ts): FFmpeg execution with base64 I/O

• Tools (src/tools/ffmpeg.ts): MCP tool definitions

• Server (src/server.ts): Request routing

• Transport (src/transport/): STDIO and HTTP support

License

MIT License. See LICENSE file for details.