Skip to main content
Glama

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

Related MCP server: YouTube MCP Server

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]"

The PyPI package is called videolens-mcp (PyPI already has an unrelated video-lens); the command is videolens. [all] adds local Whisper and OCR. Drop it (pip install videolens-mcp) for the light install; those two tools then say what to install.

No install at all, with uv: uvx --from "videolens-mcp[all]" videolens

Claude Code

claude mcp add --scope user videolens --env PYTHONUTF8=1 -- videolens

or without installing anything first:

claude mcp add --scope user videolens --env PYTHONUTF8=1 -- uvx --from "videolens-mcp[all]" 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 (pip install videolens-mcp)

  • 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

Available Tools

13 tools
batch_transcriptsB

Transcripts of several videos in one call (max 8), each merged into 30s blocks and capped.

Inputs: urls (required), lang, max_chars_each. Returns: result

channel_statsA

Quick channel analysis over its latest n videos (max 50): average/median views, best videos, typical length and upload cadence. url like https://www.youtube.com/@name/videos

Inputs: url (required), n. Returns: result

channel_videosB

List recent videos of a channel or playlist URL (e.g. https://www.youtube.com/@name/videos).

Inputs: url (required), n. Returns: result

doctorA

Self-check: versions, which optional features are installed, and whether YouTube is reachable. Run this first if any tool misbehaves.

Inputs: no named parameters. Returns: result

find_in_videoB

Find WHERE a topic is said in a video. query: comma-separated terms (any match). Returns timestamped caption lines (with a little context). frames=True also returns the video frame at each hit.

Inputs: url (required), query (required), lang, width, +2 more.

ocr_framesA

Read the TEXT shown in a video (slides, code, UI, burned-in subtitles) without returning images, so it is cheap in tokens. Frames come from scene changes (default) or even spacing. Output: timestamp and recognised text per frame. Runs locally (rapidocr), no cloud.

Inputs: url (required), end, mode, start, +2 more. Returns: result

transcribe_videoA

Transcribe the SPEECH of a video locally with Whisper (faster-whisper, CPU) when it has no usable captions. model: tiny | base | small (bigger = slower, more accurate). lang: 'en', 'tr'... or empty to auto-detect. Max 30 min per call, so use start/end for long videos. First run downloads the model once.

Inputs: url (required), end, lang, model, +3 more. Returns: result

video_commentsA

Read YouTube comments. sort: 'top' or 'new'. replies=True adds replies (3 per thread). query: comma-separated terms; scans up to scan comments and returns only those containing any term (case-insensitive), e.g. query="broke,refund,scam". Each comment is cut to max_chars_each.

Inputs: url (required), scan, sort, query, +3 more. Returns: result

video_infoC

Get YouTube video metadata: title, channel, stats, upload date, tags, chapters, description.

Inputs: url (required), description_chars. Returns: result

video_transcriptA

Get video transcript (manual subs first, then auto-captions). lang='auto' (default) uses the video's spoken language; or force e.g. 'en', 'tr'. Lines merge into ~chunk_seconds blocks (0 = raw) to save tokens. Use start/end ('1:30') to read one part of a long video. No captions? use transcribe_video.

Inputs: url (required), end, lang, start, +3 more. Returns: result

watch_videoA

'Watch' a video: returns frames (images, each labelled with timestamp) plus the transcript for the same range. mode='even' spaces frames evenly; mode='scenes' samples twice as many moments and keeps the ones that differ most (best for slides, demos, edited videos). Use start/end ('90', '1:30') to zoom in and call again for detail. n_frames max 24 (default 6); width 512 saves tokens, raise to ~768 only to read small on-screen text (or use ocr_frames).

Inputs: url (required), end, lang, mode, +4 more.

youtube_researchA

Research a topic on YouTube in one call. Runs several searches (your queries, or the topic plus 'explained' and 'review' variants), merges and de-duplicates, ranks by views, recency and how many searches surfaced each video, then returns a compact brief per top video: stats, chapters, description, transcript excerpt (start/middle/end) with top terms, and top comments. Follow up with find_in_video, video_comments(query=...) or watch_video on the most promising ones. n_videos max 8.

Inputs: topic (required), lang, sort, queries, +6 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 13 tools

    Disambiguation4/5

    Each tool targets a distinct capability (metadata, comments, transcript, search, channel listing, frames, OCR, local ASR), and the descriptions explicitly state fallback relationships (e.g. video_transcript -> transcribe_video when captions are missing). The only mild overlaps are the frame-producing tools (watch_video, ocr_frames, find_in_video with frames=True) and transcript variants (video_transcript vs batch_transcripts), but the descriptions make the intended split clear.

    Naming Consistency4/5

    All names are lowercase snake_case and readable, with no camelCase or style mixing. The pattern is slightly heterogeneous: some are verb-led (find_in_video, watch_video, transcribe_video, ocr_frames) and others noun-led (video_info, channel_stats, youtube_search), plus a bare 'doctor', but this is a minor deviation rather than confusion.

    Tool Count5/5

    13 tools sit comfortably in the well-scoped range, and each one earns its place: core reads, search/research aggregation, channel analysis, frame/OCR inspection, and a local ASR fallback. Nothing feels redundant or padded, and there are no missing bulk/utility helpers.

    Completeness5/5

    For a YouTube analysis/research domain the surface is thorough: metadata, comments, transcripts (single and batch), in-video search, search and multi-query research, channel/playlist listing and stats, visual frames, OCR, and a Whisper fallback for uncaptioned videos, plus a doctor self-check. Read-only by design, so the absence of write operations is not a gap.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      An MCP server that provides YouTube data access without API keys or quotas. It enables agents to search videos, retrieve transcripts and metadata, and perform full-text search across cached content for AI context retrieval.
      3 npm
      -