mnehmos.ffmpeg-llm.mcp

FFmpeg-based video editing engine exposed as an MCP (Model Context Protocol) server with OpenRouter LLM autopilot.

You don't need a video editor — you need a video editing engine with MCP tool exposure.

What is this?

An MCP server that gives AI agents structured control over FFmpeg. Instead of writing raw FFmpeg commands, agents call tools like clip_add, clip_trim, preview_segment, and render_full. The server maintains a JSON timeline as the source of truth and generates optimized FFmpeg filter graphs at render time.

47 tools across 8 categories: Project Management, Asset Management, Timeline Editing, Chapters, Preview & Render, Analysis, Chess Content Pipeline, and LLM Autopilot.

Features

• Structured timeline editing — Tracks, clips, filters, chapters as JSON
• FFmpeg filter graph generation — Timeline → optimized -filter_complex commands
• Preview engine — Quick low-res previews before committing to full renders
• Audio/scene analysis — Silence detection, scene changes, audio levels via FFmpeg
• Chess content pipeline — Game boundary detection, overlays, YouTube export
• LLM autopilot — OpenRouter vision models analyze video, suggest edits, identify highlights
• Background rendering — Long exports run async with progress tracking
• Undo/redo — Full operation history

Prerequisites

• Node.js >= 18
• FFmpeg >= 4.0 (in PATH)
• ffprobe >= 4.0 (in PATH)

Installation

git clone https://github.com/Mnehmos/mnehmos.ffmpeg-llm.mcp.git
cd mnehmos.ffmpeg-llm.mcp
npm install
npm run build

Usage

As MCP Server

Add to your MCP client configuration:

{
  "mcpServers": {
    "ffmpeg-llm": {
      "command": "node",
      "args": ["path/to/mnehmos.ffmpeg-llm.mcp/dist/index.js"],
      "env": {
        "OPENROUTER_API_KEY": "your-key-here"
      }
    }
  }
}

Quick Start

1. project_create({ name: "My Video", workDir: "/path/to/project" })
2. asset_import({ projectId: "...", filePath: "/path/to/recording.mp4" })
3. clip_add({ projectId: "...", assetId: "...", trackId: "...", timelineStart: 0 })
4. clip_trim({ clipId: "...", sourceStart: 30, sourceEnd: 120 })
5. preview_segment({ projectId: "...", start: 0, end: 10 })
6. render_full({ projectId: "...", outputPath: "/path/to/output.mp4" })

Development

npm run dev            # Run with tsx
npm run test           # Run tests
npm run test:watch     # Watch mode
npm run test:coverage  # With coverage
npm run preflight      # typecheck + lint + test

Architecture

See DESIGN.md for full architecture documentation.

License

MIT