Video Frames MCP server

mcp-video-frames — Video MCP Server

<!-- mcp-name: io.github.Azzy-H/mcp-video-frames -->

An MCP server that lets image-only models look at video: frames with timecodes, plus measurable video properties.

Available Tools

The server provides these tools:

• view_frames - Sample a time range and return frames as images, each preceded by its timecode
• video_info - Container metadata, optionally with a whole-file scene/silence/loudness scan

The model you are talking to must accept image input. Without it, the returned frames are dropped or degraded to text.

This is a local server: it is not hosted anywhere, and a client has to be pointed at it. See Self-Hosted below.

Install from PyPI

pip install mcp-video-frames      # or run it without installing: uvx mcp-video-frames

That installs one console script, and the console script is the server. Point a client at it:

{
  "mcpServers": {
    "video-frames": { "command": "mcp-video-frames" }
  }
}

With no subcommand and piped stdio it speaks MCP; on a terminal it prints help instead of hanging. mcp-video-frames doctor checks the environment it will run in.

This path expects ffmpeg and ffprobe on PATH. If you would rather have them installed into a private virtual environment, along with a ready-made client config, use Self-Hosted below instead.

Self-Hosted

Installs nothing into your system Python: dependencies go into the project's own .venv/, and the client config points at that interpreter directly.

1. Clone the repository

git clone https://github.com/Azzy-H/mcp-video-frames.git
cd mcp-video-frames

1. Generate the virtual environment and the client config

python setup_mcp.py

setup_mcp.py only does three things:

1. creates .venv/ in this directory (run it with any Python 3.10+ interpreter);
2. installs the two runtime dependencies from requirements.txt into that .venv/;
3. writes mcp-config.json, with the paths already filled in.

Options:

python setup_mcp.py --max-images 12      # match your client's image limit
python setup_mcp.py --print              # print the config only; write nothing
python setup_mcp.py --ffmpeg <path>      # ffmpeg is not on PATH

If ffmpeg is missing the script offers to download a prebuilt build into .venv/ (Windows), to point at one you installed, or to skip. Nothing is ever installed system-wide.

1. Check the environment before wiring it up

.venv/Scripts/python run_server.py doctor     # Windows
.venv/bin/python     run_server.py doctor     # macOS / Linux

This reports the ffmpeg/ffprobe paths and versions, whether the required filters are present, and whether the cache directory is writable — naming whatever is missing rather than leaving you to guess. It finds a venv-local ffmpeg on its own, so nothing has to be exported first.

test_server.py goes further and speaks real MCP to the server over stdio, so the whole path can be verified before any client is configured:

.venv/Scripts/python test_server.py connect <video file path>   # Windows
.venv/bin/python     test_server.py connect <video file path>   # macOS / Linux

It checks the handshake, the tool list, the 2n + 1 content-block ordering, whether a single-frame request comes back as PNG, and that an over-limit request is refused — and that stdout stays clean for the JSON-RPC stream.

1. Add this MCP server

Shortened. The full README is on GitHub.