Skip to main content
Glama

📸 Video Screenshot MCP

npm version License: MIT Node.js Version TypeScript MCP Compatible

一个基于 Model Context Protocol (MCP) 的视频截图服务,支持高质量的视频帧提取和批量截图功能。

✨ 特性

  • 🎯 精确截图: 支持毫秒级精度的视频帧提取

  • 📊 批量处理: 按时间间隔批量截取视频画面

  • 🔍 视频信息: 获取视频详细信息(时长、分辨率、帧率等)

  • 🖼️ 多格式支持: 支持 JPG、PNG、WebP 输出格式

  • ⚙️ 灵活配置: 可自定义输出质量、尺寸等参数

  • ✅ 文件验证: 智能验证视频文件有效性

  • 🚀 高性能: 基于 FFmpeg 的高效视频处理

Related MCP server: ScreenshotOne MCP Server

📦 安装

作为 MCP 服务使用(推荐)

在您的 IDE 配置文件中添加以下配置:

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

本地安装

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

🚀 快速开始

在 IDE 中配置

Cursor / VS Code

在 settings.json 中添加:

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

Claude Desktop

在 claude_desktop_config.json 中添加:

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

基本用法示例

配置完成后,您可以通过 AI 助手使用以下功能:

请帮我截取视频 /path/to/video.mp4 在第 30 秒的画面
请批量截取视频每 10 秒的画面,保存为 PNG 格式
请获取这个视频文件的详细信息

📖 API 参考

🔍 get_video_info

获取视频文件的详细信息。

参数:

  • videoPath (string): 视频文件路径

返回: 包含时长、分辨率、帧率、编码格式等信息的对象

📸 take_screenshot

在指定时间点截取视频单帧画面。

参数:

  • videoPath (string): 视频文件路径

  • timestamp (number): 截图时间点(秒)

  • outputPath (string): 输出文件路径

  • format (string, 可选): 输出格式 (jpg/png/webp),默认 jpg

  • quality (number, 可选): 图片质量 (1-100),默认 90

  • width (number, 可选): 输出宽度(像素)

  • height (number, 可选): 输出高度(像素)

📷 batch_screenshot

按固定时间间隔批量截取视频画面。

参数:

  • videoPath (string): 视频文件路径

  • interval (number): 截图时间间隔(秒)

  • startTime (number, 可选): 开始时间(秒),默认 0

  • endTime (number, 可选): 结束时间(秒),默认视频结束

  • maxCount (number, 可选): 最大截图数量

  • outputDir (string, 可选): 输出目录,默认 ./screenshots

  • prefix (string, 可选): 文件名前缀,默认 screenshot

  • format (string, 可选): 输出格式,默认 jpg

  • quality (number, 可选): 图片质量,默认 90

  • width (number, 可选): 输出宽度(像素)

  • height (number, 可选): 输出高度(像素)

✅ validate_video

验证视频文件是否有效且支持处理。

参数:

  • videoPath (string): 视频文件路径

返回: 验证结果和错误信息(如有)

🎯 使用场景

  • 📝 内容创作: 为视频制作缩略图和预览图

  • 🎬 视频分析: 提取关键帧进行内容分析

  • 📊 质量检测: 批量检查视频质量和内容

  • 🔍 素材管理: 为视频库生成预览图

  • 🎨 设计工作: 提取视频帧用于设计素材

🛠️ 疑难解答

❌ 常见问题

问题 1: Connection closed 错误

症状: 在使用 MCP 服务时出现连接关闭错误

解决方案(按推荐顺序):

  1. 🎯 首选方案: 确认使用了 @latest 标签

    {
      "command": "npx",
      "args": ["@pickstar-2002/video-screenshot-mcp@latest"]
    }
  2. 🔄 备用方案: 锁定到特定稳定版本

    {
      "command": "npx",
      "args": ["@pickstar-2002/video-screenshot-mcp@1.1.1"]
    }
  3. 🧹 终极方案: 清理 npx 缓存

    # 清理 npx 缓存
    npx clear-npx-cache
    
    # 或者手动删除缓存目录
    # Windows: %USERPROFILE%\.npm\_npx
    # macOS/Linux: ~/.npm/_npx

问题 2: FFmpeg 未找到

症状: 提示 FFmpeg 不可用或未安装

解决方案:

# Windows (使用 Chocolatey)
choco install ffmpeg

# macOS (使用 Homebrew)
brew install ffmpeg

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

# CentOS/RHEL
sudo yum install ffmpeg

问题 3: 权限错误

症状: 无法读取视频文件或写入截图

解决方案:

  • 确保视频文件路径正确且可访问

  • 检查输出目录的写入权限

  • 在 Windows 上可能需要以管理员身份运行

问题 4: 视频格式不支持

症状: 某些视频文件无法处理

解决方案:

  • 使用 validate_video 工具检查文件有效性

  • 支持的格式: MP4, AVI, MOV, MKV, WebM, FLV 等主流格式

  • 对于特殊格式,建议先转换为 MP4

📋 调试技巧

  1. 启用详细日志: 设置环境变量 DEBUG=video-screenshot:*

  2. 检查文件路径: 使用绝对路径避免相对路径问题

  3. 测试小文件: 先用小视频文件测试功能

  4. 查看错误信息: 仔细阅读错误消息中的具体提示

🔧 系统要求

  • Node.js: >= 18.0.0

  • FFmpeg: 需要系统安装 FFmpeg

  • 操作系统: Windows, macOS, Linux

  • 内存: 建议至少 512MB 可用内存

📄 许可证

本项目采用 MIT 许可证。

🤝 贡献

欢迎提交 Issue 和 Pull Request!

开发环境设置

# 克隆仓库
git clone https://github.com/pickstar-2002/video-screenshot-mcp.git
cd video-screenshot-mcp

# 安装依赖
npm install

# 构建项目
npm run build

# 运行测试
npm test

📞 联系方式

如有问题或建议,欢迎联系:

微信: pickstar_loveXX


⭐ 如果这个项目对您有帮助,请给个 Star 支持一下!

Available Tools

4 tools
batch_screenshotC

按固定时间间隔批量截取视频画面

Inputs: interval (required), videoPath (required), endTime, format, +7 more.

get_video_infoB

获取视频文件的详细信息,包括时长、分辨率、帧率等

Inputs: videoPath (required).

take_screenshotC

在指定时间点截取视频单帧画面

Inputs: outputPath (required), timestamp (required), videoPath (required), format, +3 more.

validate_videoC

验证视频文件是否有效且支持处理

Inputs: videoPath (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no ambiguity. batch_screenshot handles interval-based captures, take_screenshot targets single frames at specific times, get_video_info retrieves metadata, and validate_video checks file validity. The descriptions make it easy to differentiate their functions.

    Naming Consistency5/5

    All tools follow a consistent verb_noun naming pattern (e.g., batch_screenshot, get_video_info, take_screenshot, validate_video). The style is uniform throughout, using snake_case with clear, descriptive verbs that align with their actions.

    Tool Count5/5

    With 4 tools, the count is well-scoped for the server's video screenshot purpose. Each tool earns its place by covering key operations: validation, metadata retrieval, single-frame capture, and batch processing, without being excessive or insufficient.

    Completeness4/5

    The tool set provides strong coverage for core video screenshot workflows, including validation, info retrieval, and screenshot capture in both single and batch modes. A minor gap exists in lacking tools for post-processing (e.g., editing or saving screenshots), but agents can work around this with existing tools.

    Related MCP Connectors

    Related MCP Servers