Skip to main content
Glama
pickstar-2002

Video Screenshot MCP

by pickstar-2002
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

📸 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

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

ParametersJSON Schema
NameRequiredDescriptionDefault
endTimeNo结束时间（秒），默认为视频结束
formatNo输出格式，默认为 jpg
heightNo输出高度（像素）
intervalYes截图时间间隔（秒）
maxCountNo最大截图数量
outputDirNo输出目录，默认为 ./screenshots
prefixNo文件名前缀，默认为 screenshot
qualityNo图片质量（1-100，仅对 jpg 有效），默认为 90
startTimeNo开始时间（秒），默认为 0
videoPathYes视频文件路径
widthNo输出宽度（像素）

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action (batch screenshot capture) but doesn't describe what happens: whether files are saved to disk, if the operation is resource-intensive, potential errors, or output format. For a tool with 11 parameters and no annotations, this is a significant gap in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence in Chinese that directly states the tool's purpose without redundancy. It's appropriately sized and front-loaded, with zero wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (11 parameters, batch file operations) and lack of annotations or output schema, the description is incomplete. It doesn't cover behavioral aspects like file output location, error handling, or performance implications, leaving the agent with insufficient context for safe and effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with all parameters well-documented in the input schema (e.g., descriptions for 'interval,' 'format,' 'outputDir'). The description adds no additional parameter semantics beyond implying time-based batch processing. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: '按固定时间间隔批量截取视频画面' translates to 'batch capture video screenshots at fixed time intervals.' This specifies the verb (capture screenshots), resource (video), and scope (batch at intervals). However, it doesn't explicitly distinguish from sibling tools like 'take_screenshot' (which might capture a single screenshot).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'take_screenshot' or 'get_video_info.' It doesn't mention prerequisites, constraints, or typical use cases. The agent must infer usage from the purpose alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_video_infoB

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

ParametersJSON Schema
NameRequiredDescriptionDefault
videoPathYes视频文件路径

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes what information is returned (duration, resolution, frame rate) but doesn't cover important behavioral aspects such as error handling (e.g., what happens if the video file doesn't exist), performance characteristics, or whether it requires specific permissions. This is a significant gap for a tool with no annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose with relevant examples. It's front-loaded with the main action and includes no unnecessary information, making it highly concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose but lacks details on behavioral traits and usage guidelines. With no output schema, it doesn't explain return values beyond the examples provided, leaving gaps in completeness for effective agent use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage (the 'videoPath' parameter is documented as '视频文件路径' - video file path), so the schema does the heavy lifting. The description doesn't add any parameter-specific details beyond what's in the schema, such as format examples or constraints. Baseline 3 is appropriate when schema coverage is high.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: '获取视频文件的详细信息，包括时长、分辨率、帧率等' (Get detailed information about video files, including duration, resolution, frame rate, etc.). It specifies the verb ('获取' - get) and resource ('视频文件' - video files) with examples of information returned. However, it doesn't differentiate from sibling tools like 'validate_video' which might have overlapping functionality.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'validate_video' (which might check video validity rather than retrieve metadata) or explain scenarios where this tool is preferred. The usage context is implied but not explicitly stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

take_screenshotC

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

ParametersJSON Schema
NameRequiredDescriptionDefault
formatNo输出格式，默认为 jpg
heightNo输出高度（像素）
outputPathYes输出文件路径
qualityNo图片质量（1-100，仅对 jpg 有效），默认为 90
timestampYes截图时间点（秒）
videoPathYes视频文件路径
widthNo输出宽度（像素）

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states what the tool does but doesn't describe important behavioral aspects: whether it modifies the original video file, what happens if the timestamp is invalid, error handling, performance characteristics, or what the output looks like (just that it's a single frame). For a tool with 7 parameters and no annotations, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise - a single sentence that directly states the core function. There's no wasted language, repetition, or unnecessary elaboration. It's front-loaded with the essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (7 parameters, no annotations, no output schema), the description is inadequate. It doesn't explain what happens when the tool executes, what the output contains, error conditions, or how it relates to sibling tools. For a tool that presumably creates files and processes video, more context about behavior and outcomes is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all parameters are documented in the schema. The description doesn't add any parameter-specific information beyond what's in the schema. It mentions '指定时间点' (specified time point) which aligns with the timestamp parameter, but this is already covered in the schema. The baseline of 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: '截取视频单帧画面' (capture a single frame from a video). It specifies the verb (截取/capture) and resource (视频单帧画面/video single frame). However, it doesn't explicitly differentiate from sibling tools like batch_screenshot (which presumably captures multiple frames) or get_video_info (which retrieves metadata rather than capturing frames).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like batch_screenshot for multiple frames, get_video_info for metadata, or validate_video for validation. There's no context about prerequisites, limitations, or appropriate scenarios beyond the basic function.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_videoC

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

ParametersJSON Schema
NameRequiredDescriptionDefault
videoPathYes视频文件路径

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. While '验证' (validate) implies a read-only check, the description doesn't specify what '有效且支持处理' (valid and supports processing) means operationally - whether it checks format compatibility, file integrity, encoding support, or other criteria. No information about error conditions, performance characteristics, or output format is provided.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient Chinese sentence that states the core purpose without unnecessary words. While appropriately concise, it could be slightly more structured by separating the validation purpose from the criteria being checked, but it's well within acceptable bounds for a simple tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a validation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what constitutes '有效且支持处理' (valid and supports processing), what validation criteria are applied, what the output looks like (success/failure, detailed diagnostics), or how this differs from simply checking file existence. The agent lacks critical context to use this tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 100% description coverage with 'videoPath' clearly documented as '视频文件路径' (video file path). The description doesn't add any parameter-specific information beyond what the schema provides, such as path format requirements or supported video locations. With complete schema coverage, the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as '验证视频文件是否有效且支持处理' (validate video file for validity and processing support), which is a specific verb+resource combination. However, it doesn't explicitly distinguish this validation tool from its siblings like 'get_video_info' which might provide similar information, keeping it from a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, timing considerations, or how it differs from sibling tools like 'get_video_info' which might also provide validation-related information. This leaves the agent without contextual usage direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 4 tool updatesv1.0.0
    • First observedbatch_screenshot
    • First observedget_video_info
    • First observedtake_screenshot
    • First observedvalidate_video
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0
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.

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/pickstar-2002/video-screenshot-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server