Video Screenshot MCP

🚀 Video Screenshot MCP

A video screenshot service based on the Model Context Protocol (MCP), supporting high-quality video frame extraction and batch screenshot functionality.

✨ Features

• 🎯 Precise Screenshots: Supports video frame extraction with millisecond-level precision.
• 📊 Batch Processing: Captures video frames in batches at specified time intervals.
• 🔍 Video Information: Retrieves detailed video information (duration, resolution, frame rate, etc.).
• 🖼️ Multiple Format Support: Supports JPG, PNG, and WebP output formats.
• ⚙️ Flexible Configuration: Allows customization of output quality, size, and other parameters.
• ✅ File Validation: Intelligently validates the effectiveness of video files.
• 🚀 High Performance: Efficient video processing based on FFmpeg.

📦 Installation

As an MCP Service (Recommended)

Add the following configuration to your IDE configuration file:

{
  "mcpServers": {
    "video-screenshot": {
      "command": "npx",
      "args": ["@pickstar-2002/video-screenshot-mcp@latest"]
    }
  }
}

Local Installation

npm install @pickstar-2002/video-screenshot-mcp

🚀 Quick Start

Configuration in IDE

Cursor / VS Code

Add the following to settings.json:

{
  "mcp.servers": {
    "video-screenshot": {
      "command": "npx",
      "args": ["@pickstar-2002/video-screenshot-mcp@latest"]
    }
  }
}

Claude Desktop

Add the following to claude_desktop_config.json:

{
  "mcpServers": {
    "video-screenshot": {
      "command": "npx",
      "args": ["@pickstar-2002/video-screenshot-mcp@latest"]
    }
  }
}

Basic Usage Example

After configuration, you can use the following features through an AI assistant:

Please take a screenshot of the video /path/to/video.mp4 at the 30th second.

Please take batch screenshots of the video every 10 seconds and save them in PNG format.

Please get the detailed information of this video file.

📚 Documentation

🔍 get_video_info

Retrieves detailed information about a video file.

Parameters:

• videoPath (string): Path to the video file.

Returns: An object containing information such as duration, resolution, frame rate, and encoding format.

📸 take_screenshot

Captures a single frame from a video at a specified time.

Parameters:

• videoPath (string): Path to the video file.
• timestamp (number): Screenshot time (in seconds).
• outputPath (string): Path to the output file.
• format (string, optional): Output format (jpg/png/webp), default is jpg.
• quality (number, optional): Image quality (1-100), default is 90.
• width (number, optional): Output width (in pixels).
• height (number, optional): Output height (in pixels).

📷 batch_screenshot

Captures video frames in batches at fixed time intervals.

Parameters:

• videoPath (string): Path to the video file.
• interval (number): Screenshot time interval (in seconds).
• startTime (number, optional): Start time (in seconds), default is 0.
• endTime (number, optional): End time (in seconds), default is the end of the video.
• maxCount (number, optional): Maximum number of screenshots.
• outputDir (string, optional): Output directory, default is ./screenshots.
• prefix (string, optional): Filename prefix, default is screenshot.
• format (string, optional): Output format, default is jpg.
• quality (number, optional): Image quality, default is 90.
• width (number, optional): Output width (in pixels).
• height (number, optional): Output height (in pixels).

✅ validate_video

Validates whether a video file is valid and can be processed.

Parameters:

• videoPath (string): Path to the video file.

Returns: Validation result and error information (if any).

🎯 Use Cases

• 📝 Content Creation: Generate thumbnails and preview images for videos.
• 🎬 Video Analysis: Extract key frames for content analysis.
• 📊 Quality Inspection: Batch check video quality and content.
• 🔍 Material Management: Generate preview images for video libraries.
• 🎨 Design Work: Extract video frames for design materials.

🛠️ Troubleshooting

❌ Common Issues

Issue 1: Connection closed error

Symptom: A connection closed error occurs when using the MCP service.

Solutions (in recommended order):

1. 🎯 Preferred Solution: Ensure the @latest tag is used.

   {
     "command": "npx",
     "args": ["@pickstar-2002/video-screenshot-mcp@latest"]
   }
   

2. 🔄 Alternative Solution: Lock to a specific stable version.

   {
     "command": "npx",
     "args": ["@pickstar-2002/video-screenshot-mcp@1.1.1"]
   }
   

3. 🧹 Ultimate Solution: Clear the npx cache.

   # Clear the npx cache
   npx clear-npx-cache
   
   # Or manually delete the cache directory
   # Windows: %USERPROFILE%\.npm\_npx
   # macOS/Linux: ~/.npm/_npx
   

Issue 2: FFmpeg not found

Symptom: FFmpeg is reported as unavailable or not installed.

Solution:

# Windows (using Chocolatey)
choco install ffmpeg

# macOS (using Homebrew)
brew install ffmpeg

# Ubuntu/Debian
sudo apt update && sudo apt install ffmpeg

# CentOS/RHEL
sudo yum install ffmpeg

Issue 3: Permission error

Symptom: Unable to read the video file or write screenshots.

Solution:

• Ensure the video file path is correct and accessible.
• Check the write permissions of the output directory.
• On Windows, you may need to run as an administrator.

Issue 4: Video format not supported

Symptom: Some video files cannot be processed.

Solution:

• Use the validate_video tool to check the file's validity.
• Supported formats: MP4, AVI, MOV, MKV, WebM, FLV, and other mainstream formats.
• For special formats, it is recommended to convert them to MP4 first.

📋 Debugging Tips

1. Enable detailed logging: Set the environment variable DEBUG=video-screenshot:*.
2. Check file paths: Use absolute paths to avoid relative path issues.
3. Test with small files: Test the functionality with small video files first.
4. Read error messages: Carefully read the specific prompts in the error messages.

🔧 System Requirements

• Node.js: >= 18.0.0
• FFmpeg: FFmpeg needs to be installed on the system.
• Operating System: Windows, macOS, Linux
• Memory: At least 512MB of available memory is recommended.

📄 License

This project is licensed under the MIT License.

🤝 Contributing

Feel free to submit issues and pull requests!

Development Environment Setup

# Clone the repository
git clone https://github.com/pickstar-2002/video-screenshot-mcp.git
cd video-screenshot-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

📞 Contact

If you have any questions or suggestions, feel free to contact us:

WeChat: pickstar_loveXX

⭐ If this project is helpful to you, please give it a star!