Video Screenshot MCP

🚀 📸 Video Screenshot MCP

一個基於 Model Context Protocol (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 格式

請獲取這個視頻文件的詳細信息

✨ 主要特性

• 🎯 精確截圖：支持毫秒級精度的視頻幀提取，確保能精準截取到所需畫面。
• 📊 批量處理：可按時間間隔批量截取視頻畫面，提高工作效率。
• 🔍 視頻信息：獲取視頻詳細信息（時長、分辨率、幀率等），方便用戶瞭解視頻情況。
• 🖼️ 多格式支持：支持 JPG、PNG、WebP 輸出格式，滿足不同場景的需求。
• ⚙️ 靈活配置：可自定義輸出質量、尺寸等參數，實現個性化截圖。
• ✅ 文件驗證：智能驗證視頻文件有效性，避免因文件問題導致的錯誤。
• 🚀 高性能：基於 FFmpeg 的高效視頻處理，快速完成截圖任務。

📦 安裝指南

作為 MCP 服務使用（推薦）

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

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

本地安裝

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

📚 詳細文檔

📖 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 支持一下！