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.