# video-reader-mcp

An [MCP](https://modelcontextprotocol.io) server that lets **Claude (or any MCP
client) read and watch online videos** — YouTube, TikTok, Douyin (抖音),
Facebook and Instagram — just by pasting a link.

Paste a URL and ask your assistant to summarize it, transcribe the speech,
describe what's on screen, or pull the metadata and comments. It gives Claude
the kind of "watch this video" ability that's otherwise built into tools like
Gemini.

## Tools

| Tool | What it does |
|------|--------------|
| `get_media_info` | Title, uploader, views/likes, upload date, description, hashtags, top comments |
| `get_transcript` | The spoken words — platform captions first, local Whisper speech-to-text as fallback |
| `get_frames` | Samples frames evenly across the video so the model can *see* it |
| `download_media` | Saves the raw video or audio file to a local folder |

## Platform support

| Platform | Status | Notes |
|----------|:------:|-------|
| YouTube | ✅ | No login needed. (Cookies are deliberately **not** sent — YouTube breaks with them.) |
| TikTok | ✅ | No login needed. |
| Facebook | ✅ | Needs your cookies (you must be logged in). |
| Instagram | ✅ | Needs your cookies. |
| Douyin (抖音) | ✅ | Needs cookies. Uses a **custom page scraper** (`douyin.py`), because yt-dlp hits Douyin's signed API and fails. Fragile — Douyin changes its page format from time to time. |

## How it works

Built on [yt-dlp](https://github.com/yt-dlp/yt-dlp) (downloads + metadata),
[ffmpeg](https://ffmpeg.org) (frame extraction),
[youtube-transcript-api](https://github.com/jdepoix/youtube-transcript-api)
(fast YouTube captions) and optional
[faster-whisper](https://github.com/SYSTRAN/faster-whisper) (local speech-to-text).

Douyin is special: yt-dlp can't get past Douyin's request-signature wall
(`msToken`/`a_bogus`), so `douyin.py` instead fetches the public share page and
parses the embedded JSON blob (`_ROUTER_DATA` / `RENDER_DATA`) for the metadata
and the CDN play URL — then streams that directly for frames/transcript.

---

## Installation

### 1. Prerequisites
- **Python 3.10+**
- **ffmpeg** (needed for `get_frames` and Whisper transcription)
  - macOS: `brew install ffmpeg`
  - Windows: `winget install Gyan.FFmpeg` (or `choco install ffmpeg`)
  - Linux: `sudo apt install ffmpeg`

### 2. Get the code and install dependencies

```bash
git clone https://github.com/s8zvp68zyn-ctrl/video-reader-mcp.git
cd video-reader-mcp
python3 -m venv .venv
# macOS / Linux:
./.venv/bin/pip install -r requirements.txt
# Windows (PowerShell):
#   .venv\Scripts\pip install -r requirements.txt
```

(Don't want the heavier Whisper dependency? Remove the `faster-whisper` line
from `requirements.txt` before installing — platform captions still work.)

### 3. Test it before wiring it up

```bash
# macOS / Linux:
./.venv/bin/python test_tools.py "https://www.youtube.com/watch?v=jNQXAC9IVRw"
# Windows:
#   .venv\Scripts\python test_tools.py "https://www.youtube.com/watch?v=jNQXAC9IVRw"
```

You should see metadata, a few transcript lines, and `test_frame_*.jpg` files.

### 4. Connect it to your MCP client (e.g. Claude Desktop)

Add the server to your client's MCP config. For **Claude Desktop**, edit:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Use `claude_desktop_config.example.json` as a template — **replace the
`/ABSOLUTE/PATH/TO/...` placeholders with real absolute paths.** On Windows the
command path is `...\.venv\Scripts\python.exe`. If the config already has other
servers, just add the `video-reader` entry inside the existing `mcpServers`.

Then fully **quit and reopen** the app. New tools load when a fresh chat starts.

---

## Cookies (for Facebook, Instagram, Douyin)

YouTube and TikTok work with no setup. The other three are login-walled, so the
server needs your browser session as a `cookies.txt` (Netscape format). The
easiest way — no extension needed — uses yt-dlp to export from your browser:

```bash
# Be logged into the sites in your browser first.
# For Douyin, also open douyin.com once so cookies are "fresh".
./.venv/bin/yt-dlp --cookies-from-browser chrome --cookies cookies.txt \
    --skip-download --no-warnings "https://www.youtube.com/watch?v=jNQXAC9IVRw"
```

Replace `chrome` with `safari`, `edge`, `firefox`, `brave`, etc.
(On macOS you'll get a Keychain prompt for "Chrome Safe Storage" — allow it. If
the cookie DB is locked, quit the browser and retry.)

Then point the server at the file via `VIDEO_READER_COOKIES_FILE` (see the
config example).

**Cookies expire** (days to weeks). When Facebook/Instagram/Douyin suddenly stop
working, just re-run the export above and restart your client.

> ⚠️ **Security:** `cookies.txt` is your live login session — it is git-ignored
> by default. Never commit or share it.

---

## Configuration (environment variables)

| Variable | Default | Purpose |
|----------|---------|---------|
| `VIDEO_READER_COOKIES_FILE` | *(none)* | Path to your `cookies.txt`. Applied only to FB/IG/Douyin. |
| `VIDEO_READER_COOKIES_BROWSER` | *(none)* | Alternative: read cookies live from a browser (e.g. `chrome`). Often unreliable for background app processes — a file is more robust. |
| `VIDEO_READER_DOWNLOAD_DIR` | `~/Downloads/video-reader` | Where `download_media` saves files. |
| `VIDEO_READER_WHISPER_MODEL` | `base` | Whisper size: `tiny`/`base`/`small`/`medium`/`large-v3`. Bigger = more accurate, slower. |

---

## Troubleshooting

- **Tools don't appear** → invalid JSON in the config (no trailing commas, use
  straight quotes — don't edit it in a rich-text editor), or the client wasn't
  fully restarted.
- **YouTube: "No video formats found"** → you attached cookies to YouTube. Don't
  — the server already skips cookies for YouTube/TikTok; make sure you didn't
  hard-code them elsewhere.
- **Facebook/Instagram errors** → expired or missing cookies. Re-export.
- **Douyin: "Fresh cookies needed" / no data** → re-export cookies after visiting
  douyin.com logged in. If it still fails, Douyin likely changed its page format;
  fix the parser in `douyin.py` (`_extract_blob` / `_find_aweme`).
- **A site stopped working generally** → `pip install -U yt-dlp` (platforms
  change often).

---

## Legal / responsible use

This tool automates access to content you can already view in a browser. Scraping
Facebook, Instagram and Douyin is against their Terms of Service, and those
extractors are fragile by nature. Only access content you're authorized to view,
respect copyright and platform rules, and use your own accounts at your own risk.
Provided as-is under the MIT License.

## Contributing

Issues and PRs welcome — especially keeping the Douyin parser and platform
extractors working as the sites change.

## License

[MIT](LICENSE)