# video-watcher MCP server

An MCP server that lets Claude Desktop "watch" videos from YouTube, Instagram,
Facebook, or a direct video URL (mp4/webm/etc), and answer questions about
them.

## What it does

For any supported URL, the server:
1. Downloads the video with `yt-dlp` (works for YouTube, Instagram, Facebook,
   and hundreds of other sites, plus falls back to a raw HTTP download for
   plain file URLs).
2. Extracts a transcript — YouTube captions via `youtube-transcript-api` if
   available, otherwise audio transcription via `faster-whisper`.
3. Extracts 5 key frames (sampled across the video's timeline) as base64 JPEGs
   using OpenCV.

Results are cached in memory per URL for the life of the process, so calling
multiple tools on the same video only downloads/transcribes it once.

## Tools

- **`watch_video(url)`** — full analysis: title, duration, transcript, frames.
- **`summarize_video(url)`** — ~200-word summary + bullet list of main points.
- **`answer_about_video(url, question)`** — transcript + frames so Claude can
  answer a specific question about the video.

## Setup

```bash
cd D:\Projects\video-mcp-server
pip install -r requirements.txt
```

You'll also need `ffmpeg` on your `PATH` (required by both `yt-dlp` for
muxing and `faster-whisper` for audio decoding). On Windows, install via
`winget install ffmpeg` or download from https://ffmpeg.org and add it to PATH.

Test the server standalone first:

```bash
python video_mcp_server.py
```

It should sit waiting on stdio (no output = good; it logs to stderr).

## Connect to Claude Desktop

Edit `%APPDATA%\Claude\claude_desktop_config.json` (create it if it doesn't
exist) and merge in:

```json
{
  "mcpServers": {
    "video-watcher": {
      "command": "python",
      "args": ["D:\\Projects\\video-mcp-server\\video_mcp_server.py"]
    }
  }
}
```

Adjust the path if you cloned this elsewhere. If `python` isn't on PATH inside
Claude Desktop's environment, use the full interpreter path instead, e.g.
`"C:\\Users\\<you>\\AppData\\Local\\Programs\\Python\\Python311\\python.exe"`.

**Fully quit and reopen Claude Desktop** after editing the config (closing the
window is not enough on Windows either — use the system tray icon to Quit).

## Testing it

Try these once connected:

- `watch_video("https://www.youtube.com/watch?v=dQw4w9WgXcQ")`
- `summarize_video("https://www.youtube.com/shorts/<some-short-id>")`
- `answer_about_video("https://www.instagram.com/reel/<reel-id>/", "What product is being promoted?")`

Ask Claude directly, e.g.: *"Watch this video and summarize it: <url>"*

## Notes & limitations

- **Instagram**: public posts/reels work via `yt-dlp`. Private accounts or
  posts requiring login will fail with a clear error — this server does not
  store or use Instagram credentials. `instagrapi` is listed as an optional
  dependency for future extension but is not required by the current code
  path.
- **Facebook**: public videos only; the same login-wall limitation applies.
- **Whisper fallback**: the first call that needs transcription will download
  the `base` Whisper model (~150MB) on first use.
- **Rate limits**: platforms may throttle repeated requests; the server
  surfaces a clear "rate limited, try again later" error rather than hanging.
- **Storage**: downloaded videos are written to a temp cache directory
  (`%TEMP%\video_mcp_cache`) and are not automatically cleaned up — clear it
  periodically if disk space matters.