MCP 服务器

mcp-ffmpeg

A job queue-based FFmpeg wrapper enabling AI assistants to perform video processing tasks such as trimming, format conversion, resolution change, and subtitle conversion through natural language.

README

MCP-FFMPEG

An MCP (Model Context Protocol) server and CLI for running FFmpeg jobs via a job queue with configurable parallel workers.

Features

Job queue — Enqueue video jobs; workers process them in the background.
Parallel workers — Run multiple jobs at once (number set in config).
Two interfaces
- CLI — Interactive menu to pick an action and enter parameters.
- MCP server — Tools for AI assistants (e.g. Claude Desktop) to enqueue and check jobs.
Actions
- Trim — Cut a segment from a video (start time + duration).
- Change video format — Convert to another container (e.g. mp4 → mkv) without re-encoding.
- Change resolution — Convert to another resolution, height and width provided by user.
- Change Subtitle format — Convert to another subtitle format (e.g. srt -> vtt).
- Extract Audio - Extract audio from an input video file
- Extract video transcript - Extracts the transcript of a video file
Caching — Same inputs produce the same job ID; completed jobs are reused unless force_run is used.

Requirements

Python 3.13+
FFmpeg — Must be on your system PATH or set via FFMPEG_PATH (see Configuration).

Installation

Choose one of the following:

Option 1: Install from PyPI

pip install mcp-ffmpeg

Or with uv:

uv add mcp-ffmpeg

Option 2: Clone the repository

git clone https://github.com/priyanshum143/MCP-FFMPEG.git
cd MCP-FFMPEG

Then install from the project root:

# With uv
uv sync

# Or with pip (editable install)
pip install -e .

Configuration

FFmpeg path
- Default: use ffmpeg from system PATH.
- Optional: set env var FFMPEG_PATH to the full path of the FFmpeg executable (e.g. for Claude Desktop).
Worker and paths
Edit src/MCP_ffmpeg/utils/variables.py (class CommonVariables):
- PARALLEL_EXECUTIONS_ALLOWED — Number of jobs that can run at once (default: 3).
- WORKER_RE_RUN_TIME — Seconds to wait between queue checks (default: 10).
- OUTPUT_DIR / LOGS_DIR — Where job outputs and logs are stored (default: outputs/ and logs/ under project root).

Running

CLI (interactive)

You get a menu: choose an action, enter the requested parameters. Jobs are enqueued and processed by background workers. Logs show which worker picked which job.

If you installed from PyPI:

mcp-ffmpeg-cli

If you cloned the repo:

# With uv (from project root)
uv run python -m MCP_ffmpeg.main

# Or after pip install -e .
mcp-ffmpeg-cli

MCP server (e.g. Claude Desktop)

Use the mcp-ffmpeg command so the MCP server runs over stdio.

If you installed from PyPI: use mcp-ffmpeg in your MCP config.

If you cloned the repo: after pip install -e ., use mcp-ffmpeg the same way. If you used uv sync, use uv run mcp-ffmpeg in the terminal, or in your MCP config use the path to your venv’s mcp-ffmpeg script so the server runs in that environment.

Add this to your %APPDATA%\Claude\claude_desktop_config.json (Windows) or the equivalent config for your MCP client:

{
  "mcpServers": {
    "mcp-ffmpeg": {
      "command": "mcp-ffmpeg",
      "env": {
        "FFMPEG_PATH": "C:\\path\\to\\your\\ffmpeg.exe"
      }
    }
  }
}

On macOS/Linux, use your normal config path and set FFMPEG_PATH to the path of your ffmpeg binary if needed.

Project layout

src/MCP_ffmpeg/
├── main.py           # CLI entrypoint
├── mcp_server.py     # MCP server entrypoint + tool definitions
├── actions/          # FFmpeg actions (trim, change format)
├── jobs/             # Job queue, manager, worker
└── utils/            # Logging, paths, CLI helpers

outputs/ — One folder per job (by job ID), containing job_details.json, output file, and optional ffmpeg_logs.log.
logs/ — Application logs.