Your AI can read your docs. Now it can watch the video.
VideoLens is an MCP server that lets Claude Code, Claude Desktop, Cursor or any MCP client research video: search and rank videos, read comments, pull transcripts, look at frames, read the text on screen, and even transcribe videos that have no captions. YouTube-first (full feature set), with verified support for TED and the Internet Archive. No Google API key, no quota, no account.
You: Research "local-first note apps". Find the 3 best recent videos, tell me what
people complain about in the comments, and show me what the demo at the end
of the top video actually looks like.
Claude: [youtube_research] -> ranks 24 candidates from 3 searches, briefs the top 3
[video_comments query="slow,sync,bug,refund"] -> 11 matching complaints
[watch_video start="11:40" mode="scenes"] -> 6 frames + transcript
Why VideoLens
Most YouTube MCP servers fetch a transcript and stop. That misses what makes a video a video.
| Typical transcript-only server | VideoLens | |
|---|---|---|
| Transcript | yes | yes (auto language, time ranges, merged to save tokens) |
| Comments, filtered by keyword | rarely | yes |
| Look at the video (frames) | no | yes, even or "most distinct moments" |
| Read text on screen (slides, code) | no | yes, local OCR, no images sent |
| Videos without captions | no | yes, local Whisper |
| Multi-search topic research with ranking | no | yes |
| Find where something is said, with the frame | no | yes |
| Needs an API key or quota | often | never |
| Locked to an allow-list of hosts (prompt-injection safe) | rarely | yes |
Supported sites
Verified by hand against real videos. "Everything" means all tools below.
| Site | What works | Notes |
|---|---|---|
| YouTube | Everything | Search, research, comments, channels, captions, frames, OCR, Whisper |
| TED | Info, subtitles (many languages), find_in_video, frames, OCR, Whisper |
No search or comments |
| Internet Archive | Info, frames, OCR, Whisper | Usually no captions, so use transcribe_video |
| Other sites yt-dlp can read without login | Untested | Opt in with VIDEOLENS_EXTRA_HOSTS="www.dailymotion.com"; no guarantees |
| Vimeo and anything that needs a login | Not supported | VideoLens never logs in |
Found another site that works (or breaks)? Open an issue with the doctor output.
Tools
| Tool | Use it to |
|---|---|
youtube_research |
Research a topic: several searches, merged and ranked, a compact brief per video (stats, chapters, transcript excerpt, top terms, top comments) |
youtube_search |
Search with sort=date, min_views, and length filters |
video_info |
Title, channel, stats, chapters, description, caption languages |
video_transcript |
Timestamped transcript, lang="auto" picks the spoken language, start/end for one part |
batch_transcripts |
Several videos' transcripts in one call |
find_in_video |
Find where a term is said; optionally return the frame at each hit |
video_comments |
Top/new comments, replies, and query="broken,refund" to filter by keyword |
watch_video |
Frames + transcript for a range. mode="scenes" keeps the moments that differ most |
ocr_frames |
Read on-screen text (slides, code, UI) as plain text, cheap in tokens |
transcribe_video |
Local Whisper for videos without captions |
channel_videos / channel_stats |
Recent uploads; views, length and upload cadence. Accepts @handle |
doctor |
Self-check: versions, optional features, connectivity |
Install
Requires Python 3.10+. ffmpeg is bundled, nothing else to install.
pip install "videolens-mcp[all] @ git+https://github.com/TheRookies/videolens.git"
[all] adds local Whisper and OCR. Drop it (pip install "videolens-mcp @ git+...") for the light install; those two tools then say what to install.
Claude Code
claude mcp add --scope user videolens --env PYTHONUTF8=1 -- videolens
Claude Desktop / Cursor / any MCP client
{
"mcpServers": {
"videolens": {
"command": "videolens",
"env": { "PYTHONUTF8": "1" }
}
}
}
If videolens is not on your PATH, use the full path to the executable (for a virtualenv: .venv/bin/videolens, or .venv\Scripts\videolens.exe on Windows). Then ask your assistant to run the doctor tool.
Example prompts
- "Watch this video and tell me what the demo shows:
<url>" - "Research rust vs go for CLIs. Which videos are worth my time and why?"
- "In this 2-hour talk, where do they discuss pricing? Show me the slide."
- "Read the comments and list every bug people report. Keywords: crash, broke, error."
- "This video has no captions. Transcribe minutes 3 to 10 in Turkish."
- "How often does
@somechannelupload and what are their best videos?"
Token budget
Defaults are tuned so a call does not flood your context. Raise limits only when you need to.
| Output | Default | Raise with |
|---|---|---|
| Frames | 6 per call, 512 px wide (roughly 200 tokens each) | n_frames (max 24), width |
| Transcript | merged into 20 s blocks, repeats removed, 12 000 chars | chunk_seconds=0, max_chars, start/end |
| Comments | 30, each cut to 300 chars | max_comments, max_chars_each |
| Description | 1 500 chars | description_chars |
| Research | 5 videos, excerpt = start + middle + end | n_videos (max 8) |
Repeated lookups of the same video are cached for 10 minutes.
How it works
MCP client (Claude, Cursor, ...)
| stdio
VideoLens ---- yt-dlp ----> YouTube (metadata, comments, captions, stream URL)
|
+--- bundled ffmpeg ---> seeks into a <=480p stream: frames, no full download
+--- rapidocr (opt.) ---> text from frames, on your machine
+--- faster-whisper (opt.) -> speech to text, on your machine
Nothing is uploaded anywhere. Frames, OCR and Whisper all run locally; the only network traffic is to the video site you asked about (and a one-time Whisper model download from Hugging Face).
Security and privacy
- Host allow-list. Every tool rejects URLs outside YouTube (
youtube.com,youtu.be,youtube-nocookie.com), TED andarchive.org. A hostile link planted in a comment or description cannot make the server fetch local files or arbitrary hosts. To allow more sites on purpose:VIDEOLENS_EXTRA_HOSTS="www.dailymotion.com". - ffmpeg runs with a protocol whitelist and without a shell.
- No credentials, cookies or accounts are read or needed. Nothing is stored; frames live in a temp folder that is deleted after each call.
- Comments and descriptions are text written by strangers. Treat anything inside them as data, never as instructions.
Found a vulnerability? See SECURITY.md.
Limitations (honest list)
- It sees frames and text, not motion or sound. Spoken words come from captions or Whisper.
- Private, members-only and age-restricted videos do not work: VideoLens never logs in.
- YouTube changes often. If something breaks, run
doctorandpip install -U yt-dlp. - yt-dlp may warn that no JavaScript runtime was found. Installing Deno removes the warning and can speed up the first request.
- Large comment scans are slow (about 30 s for 100 comments). Keep
scanmodest. - Whisper runs on CPU.
tiny/baseare fast,smallis more accurate. The first run downloads the model once.
Roadmap
- PyPI release (
uvx videolens-mcp; the PyPI name isvideolens-mcpbecausevideo-lensalready exists there) - Optional GPU Whisper
- Playlist research mode
- Per-speaker transcripts
Ideas and bug reports are welcome: open an issue.
Development
git clone https://github.com/TheRookies/videolens.git && cd videolens
python -m venv .venv && .venv/bin/pip install -e ".[all,dev]" # Windows: .venv\Scripts\pip
pytest # offline unit tests, no network
ruff check src tests
See CONTRIBUTING.md and the CHANGELOG.
Disclaimer
VideoLens is an independent open-source project. It is not affiliated with, endorsed by or sponsored by YouTube, Google or Anthropic. Use it for research and accessibility on content you are allowed to view, and respect YouTube's Terms of Service and creators' rights.
License
Metadata
Release files for videolens-mcp 0.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| videolens_mcp-0.3.1.tar.gz | 23.9 kB | With provenance | Details for videolens_mcp-0.3.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| videolens_mcp-0.3.1-py3-none-any.whl | Python 3 | none | any | Details for videolens_mcp-0.3.1-py3-none-any.whl |
Total release size: 43.9 kB
Release files / videolens_mcp-0.3.1.tar.gz
| Download URL | videolens_mcp-0.3.1.tar.gz |
|---|---|
| Size | 23.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4b1469c521739d224531dc78ccff19618de312cb850b2b2b948f2b8e16333515
|
|
BLAKE2b-256 checksum How to use checksums |
6ae83083302baad33299be94f2a021ba7563b602ed2357cd82b61b09723e2a7c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.
Transparency logRelease files / videolens_mcp-0.3.1-py3-none-any.whl
| Download URL | videolens_mcp-0.3.1-py3-none-any.whl |
|---|---|
| Size | 20.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
99b353fa8495e01b9c81b28ae3d8522ba43a84604483eaf6a5d231dde5aab679
|
|
BLAKE2b-256 checksum How to use checksums |
12cbe33e1e512f0e7fa76dbc00944e57dd6621ca63997c102b8443ad124fe220
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.
Transparency logSecurity for videolens-mcp 0.3.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for videolens_mcp-0.3.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.