video-use

An MCP server + CLI that extracts key video frames (from a local file or a video URL) so AI agents can analyze videos using images + timestamps.

Prerequisites

• ffmpeg on PATH (e.g. macOS: brew install ffmpeg)
• yt-dlp on PATH (e.g. macOS: brew install yt-dlp) — only required for URL sources
• Node.js >= 20

Install (local)

npm install
npm run build

CLI

• video-use starts the MCP stdio server (for agents)
• video-use extract <file|url> extracts frames into .video-use/frames/<runHash>/
• video-use doctor checks ffmpeg + yt-dlp
• video-use init guided setup: install MCP for selected agents, optionally install a skill, and update .gitignore
• video-use skill guided skill install for selected agents
• video-use cleanup [--run <hash>] removes downloads/frames

Output Layout

.video-use/
  downloads/<runHash>/...
  frames/<runHash>/
    000001.png
    000002.png
    manifest.json

Cursor MCP Setup (manual)

In .cursor/mcp.json:

{
  "mcpServers": {
    "video-use": {
      "command": "video-use",
      "args": []
    }
  }
}

Recommended: run video-use init to create/update the file automatically.

Guided MCP installation (recommended)

video-use init uses add-mcp under the hood to install the MCP server for the agents you choose (Cursor, VS Code/Copilot, Claude Code/Desktop, etc.).

MCP tools

• video_frames_extract: download (if URL), extract scene-change frames + fallback FPS sampling, merge, time-dedupe, cap with maxFrames, and write a manifest.
• video_probe: probe a local file (ffprobe/ffmpeg) or URL (yt-dlp metadata).
• video_cleanup: delete .video-use artifacts (optional runHash).