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 videodistorted(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 videoreference(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 videotranscoded(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.