Video Quality MCP Server

An MCP (Model Context Protocol) Server for video quality analysis and transcoding effect comparison.

Features

📹 Video Metadata Analysis - Extract encoding parameters, resolution, frame rate, etc.
🎬 GOP/Frame Structure Analysis - Analyze keyframe distribution and GOP structure
📊 Quality Metrics Comparison - Calculate objective metrics like PSNR, SSIM, VMAF
🔍 Artifact Analysis - Detect blur, blocking, ringing, banding, dark detail loss
📝 Transcode Summary - Generate LLM-friendly transcoding quality assessment reports

Installation

pip install -r requirements.txt

Running

Running as MCP Server

python main.py

The server communicates with clients via stdio protocol.

Configuration in Cursor

Add the following to your Cursor MCP configuration file:

{
  "mcpServers": {
    "video-quality": {
      "command": "python",
      "args": ["/path/to/video-quality-mcp/main.py"]
    }
  }
}

Tools

1. analyze_video_metadata

Parse video file metadata and encoding parameters.

Input:

path (string): Path to video file

Output:

Container format, duration, file size, bitrate
Video codec, profile, level, resolution, frame rate, pixel format

2. analyze_gop_structure

Analyze video GOP structure and frame type distribution.

Input:

path (string): Path to video file

Output:

I/P/B frame distribution statistics
GOP average/min/max length
Keyframe timestamp list

3. compare_quality_metrics

Compare quality metrics between two video files.

Input:

reference (string): Path to reference video
distorted (string): Path to video to evaluate

Output:

PSNR (Y/U/V components)
SSIM score
VMAF score

4. analyze_artifacts

Analyze video artifacts and perceptual quality proxy metrics.

Input:

target (string): Path to target video
reference (string, optional): Path to reference video (optional)

Output:

Single stream mode: Artifact type scores
Comparison mode: Artifact change delta values
Risk summary and likely causes

5. summarize_transcode_comparison

Generate comprehensive transcoding effect assessment report.

Input:

source (string): Path to source video
transcoded (string): Path to transcoded video

Output:

Quality change verdict
VMAF delta and bitrate savings
Key issues list
Encoding parameter optimization recommendations

Technical Implementation

FFmpeg/ffprobe Wrapper - Unified command-line interface
No Deep Learning Dependencies - Uses traditional image processing and signal analysis methods
Structured Output - All tools return standard JSON format
Error Handling - Clear error message return mechanism

Requirements

Python 3.10+
FFmpeg (must be installed and configured in PATH)
Python packages listed in requirements.txt

Notes

Ensure FFmpeg is properly installed with VMAF support
Large file analysis may take a long time
All paths should preferably use absolute paths

Documentation

For Chinese documentation, see README.zh.md.