video-reader-mcp

An MCP 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 (downloads + metadata), ffmpeg (frame extraction), youtube-transcript-api (fast YouTube captions) and optional 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

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

# 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:

# 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