Skip to main content

VideoLens: give your AI eyes on video

CI License: MIT Python 3.10+ MCP server No API key

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 @somechannel upload 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 and archive.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 doctor and pip 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 scan modest.
  • Whisper runs on CPU. tiny/base are fast, small is more accurate. The first run downloads the model once.

Roadmap

  • PyPI release (uvx videolens-mcp; the PyPI name is videolens-mcp because video-lens already 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

MIT

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)

Source distribution for videolens-mcp 0.3.1
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)

Table of built distributions (wheels) for videolens-mcp 0.3.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.3.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page