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.