mcp-server-video-context

MCP server that analyzes videos and extracts structured text context optimized for AI consumption.

Pipeline: Video → Smart Frame Extraction → OCR → Text Classification → Token-Optimized Markdown

Features

• Scene detection — ffmpeg-based scene change detection with configurable sensitivity
• Perceptual dedup — Parallel hash-based deduplication removes near-identical frames
• OCR — Tesseract.js text extraction with persistent worker (no re-init overhead)
• Text classification — Prioritizes errors, stack traces, code over UI labels
• Caching — File-based cache with TTL expiry and secure permissions (0600)
• Multi-source download — 4-tier strategy: direct HTTP, yt-dlp, browser fallback, local file
• Security hardened — SSRF protection, path traversal prevention, input sanitization, TLS enforcement
• Concurrency safe — Semaphore-controlled parallel analyses with proper resource cleanup

Quick Start

Option 1 — Claude Code CLI (recommended):

claude mcp add video-context npx -- -y @cf-lp/mcp-server-video-context

Option 2 — Manual config (claude_desktop_config.json / MCP settings):

{
  "mcpServers": {
    "video-context": {
      "command": "npx",
      "args": ["-y", "@cf-lp/mcp-server-video-context"]
    }
  }
}

Tools

analyze_video

Analyze a video and get structured context.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | video_url | string | * | URL to download video from | | video_path | string | * | Local file path | | auth_header | string | No | Authorization header for URL download | | max_frames | number | No | Max frames to analyze (default from MAX_FRAMES env) | | include_frames | boolean | No | Include base64 thumbnails (default: false) | | use_browser | boolean | No | Force browser-based download (default: false) |

* Provide exactly one of video_url or video_path.

get_cached_analysis

Retrieve cached analysis results.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | video_url | string | * | URL used in original analysis | | video_path | string | * | Path used in original analysis | | cleanup_expired | boolean | No | Clean up expired cache entries |

* At least one of video_url or video_path is required.

browser_download

Download a video via the system browser (for SSO/OAuth-protected URLs).

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | url | string | Yes | URL to download | | jira_domain | string | No | Jira domain for attachment URL conversion | | filename | string | No | Expected filename |

open_in_browser

Open a URL in the system default browser.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | url | string | Yes | URL to open (http/https only) |

Video URL Support

analyze_video supports all common video sources via a 4-tier download strategy:

1. Direct HTTP fetch — fast path for direct video URLs (.mp4, .webm, .mov, .avi, .mkv, .m4v, .ts, .flv)
2. yt-dlp extraction — YouTube, Vimeo, TikTok, Twitter/X, Facebook, Instagram, Google Drive, Dropbox, HLS/DASH streams, and 1000+ other sites
3. Browser download — fallback for SSO/OAuth-protected URLs (opens user's default browser)
4. Local file — pass video_path for already-downloaded files

URL routing is automatic — just pass any video URL to analyze_video(video_url=...).

yt-dlp (Optional but Recommended)

yt-dlp enables automatic download from video platforms without user interaction.

brew install yt-dlp          # macOS
pip install yt-dlp            # cross-platform

The server works without yt-dlp but falls back to browser download for platform URLs.

Workflow with Jira (Atlassian MCP)

1. Use Atlassian MCP → getJiraIssue("PROJ-123") → get attachment URLs
2. Use browser_download → download via authenticated browser session
3. Use analyze_video(video_path=...) → get structured markdown context

Output Format

## Video: recording.mp4 | 2m34s | 1920x1080 | 18 frames analyzed

### Timeline
| Time | Key Text |
|------|----------|
| 0:00 | Sign in to Dashboard, Email, Password |
| 0:12 | Error: 500 Internal Server Error |

### Errors & Stack Traces
- 500 Internal Server Error
- TypeError: Cannot read property 'map' of undefined at App.jsx:42

### UI Labels
Sign in, Dashboard, Settings

Environment Variables

All optional:

| Variable | Default | Description | |----------|---------|-------------| | CACHE_DIR | ~/.cache/mcp-video-context | Cache directory | | CACHE_TTL_HOURS | 168 (7 days) | Cache expiry | | MAX_FRAMES | 30 | Default max frames (1-200) | | SCENE_THRESHOLD | 0.3 | Scene change sensitivity (0.0-1.0) | | FFMPEG_PATH | auto-detected | Custom ffmpeg path | | YT_DLP_PATH | auto-detected | Custom yt-dlp path | | YT_DLP_TIMEOUT | 600000 (10 min) | yt-dlp download timeout (ms) | | MAX_VIDEO_SIZE_MB | 500 | Max video download size (10-5000 MB) |

Security

• SSRF protection — DNS resolution validates against private IP ranges before fetching
• Path traversal prevention — video_path is resolved and validated
• Input sanitization — Auth headers reject newline injection, URLs validate scheme
• TLS enforced — All external connections use certificate verification
• Secure cache — Files created with 0600 permissions, directories with 0700
• URL logging — Query parameters redacted from logs to prevent token leakage
• Concurrency limits — Max 2 concurrent analyses prevent resource exhaustion

Requirements

• Node.js >= 18

ffmpeg is bundled automatically — no manual installation needed. yt-dlp is optional but recommended for platform video URLs (YouTube, Vimeo, etc.).

Development

npm install
npm run build        # Build with tsup
npm run dev          # Watch mode
npm run inspect      # MCP Inspector

License

MIT