# 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
```bash
pip install -r requirements.txt
```
## Running
### Running as MCP Server
```bash
python main.py
```
The server communicates with clients via stdio protocol.
### Configuration in Cursor
Add the following to your Cursor MCP configuration file:
```json
{
"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](README.zh.md).
