Skip to main content
Glama

πŸ” What is VidLens?

Stop watching 10 videos to answer one question. VidLens searches YouTube, reads the transcripts, and synthesizes what creators actually said β€” across multiple videos, with timestamps, benchmark charts, and sources.

VidLens is a Model Context Protocol server that gives AI agents deep, reliable access to YouTube. Not just transcripts β€” full intelligence: search, analysis, visual search, and auto-generated comparison charts.

No API key required to start. Every tool has a three-tier fallback chain (YouTube API β†’ yt-dlp β†’ page extraction) so nothing breaks when quota runs out or keys aren't configured.

Try it β€” paste any of these into Claude:

"I'm thinking about buying the M5 Max MacBook Pro. Search YouTube for top tech reviewers and tell me what they're saying. Is it worth the upgrade from M3/M4?"

VidLens finds 10+ reviews, reads the transcripts, extracts benchmark scores, and presents comparison charts β€” all from one prompt.

"I want to understand how AI agents work. Search YouTube for the best videos for a beginner and summarize what I need to know."

Discovers videos across creators, ranks by learning value, and prepares transcripts for follow-up questions.

"Search YouTube for reviews comparing the iPhone 17 Pro vs Samsung S26 Ultra. What do reviewers agree on? Where do they disagree?"

Searches, reads transcripts from multiple reviewers, and synthesizes consensus vs disagreements with sources.


🎯 Core Capabilities

πŸ” Explore β€” One Prompt, Full Pipeline

Ask a question about YouTube and VidLens does the rest: searches, ranks by creator match and freshness, reads transcripts, extracts benchmark data, and presents comparison charts automatically. Works for product research, learning, competitive analysis β€” anything on YouTube.

πŸ”Ž Semantic Search Across Playlists

Import entire playlists or video sets, index every transcript with Gemini embeddings, and search across hundreds of hours of content by meaning β€” not just keywords.

πŸ‘οΈ Visual Search β€” See What's In Videos

Extract keyframes, describe them with Gemini Vision, run OCR on slides and whiteboards, and search by what you see β€” not just what's said.

πŸ“Š Intelligence Layer β€” Not Just Data

Sentiment analysis, niche trend discovery, content gap detection, hook pattern analysis, upload timing recommendations. The LLM does the thinking β€” VidLens gives it the right data.

⚑ Zero Config, Always Works

No API key needed to start. Three-tier fallback chain on every tool. Nothing breaks when quota runs out. Keys are optional power-ups.

🎬 Full Media Pipeline

Download videos/audio/thumbnails. Extract keyframes. Index comments for semantic search. Build a local knowledge base from any YouTube content.


⚑ Why VidLens?


πŸš€ Quick Start

1. Install

npx vidlens-mcp setup

This auto-detects your MCP clients (Claude Desktop, Claude Code) and configures both.

2. Or configure manually

Claude Desktop β€” add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "vidlens-mcp": {
      "command": "npx",
      "args": ["-y", "vidlens-mcp", "serve"]
    }
  }
}

Claude Code β€” add to ~/.claude/settings.json:

{
  "mcpServers": {
    "vidlens-mcp": {
      "command": "npx",
      "args": ["-y", "vidlens-mcp", "serve"]
    }
  }
}

3. Restart your MCP client

Fully quit and reopen Claude Desktop (⌘Q). Claude Code picks up changes automatically.

4. Try it

Start with "Search YouTube" to activate VidLens:

"Search YouTube for the top M5 Max MacBook Pro reviews and tell me if it's worth upgrading from M4."

"Search YouTube for the best videos about agentic AI for a beginner."

"Import this playlist and search across all videos for mentions of machine learning."

"Search this video's frames for the benchmark comparison chart."

"What's trending in the AI coding niche right now?"


🧰 Tools - 41 across 10 modules

πŸ” Explore - YouTube Discovery & Research

The front door β€” one prompt, full pipeline

Tool

What it does

exploreYouTube

Intent-aware search with multi-query ranking, parallel enrichment, transcript summaries, structured benchmark data, and background indexing. One call replaces 5-8 individual tool calls.

πŸ“Ί Core - Video & Channel Intelligence

Always available, no API key needed

Tool

What it does

findVideos

Search YouTube by query with metadata

inspectVideo

Deep metadata - tags, engagement, language, category

inspectChannel

Channel stats, description, recent uploads

listChannelCatalog

Browse a channel's full video library

readTranscript

Full transcript with timestamps and chapters

readComments

Top comments with likes and engagement

expandPlaylist

List all videos in any playlist

Index transcripts and search across them with natural language

Tool

What it does

importPlaylist

Index an entire playlist's transcripts

importVideos

Index specific videos by URL/ID

searchTranscripts

Natural language search across indexed content

listCollections

Browse your indexed collections

setActiveCollection

Scope searches to one collection

clearActiveCollection

Search across all collections

removeCollection

Delete a collection and its index

πŸ’¬ Sentiment & Analysis

Understand what audiences think and feel

Tool

What it does

measureAudienceSentiment

Comment sentiment with themes and risk signals

analyzeVideoSet

Compare performance across multiple videos

analyzePlaylist

Playlist-level engagement analytics

buildVideoDossier

Complete single-video deep analysis

🎯 Creator Intelligence

Insights for content strategy

Tool

What it does

scoreHookPatterns

Analyze what makes video openings work

researchTagsAndTitles

Tag and title optimization insights

compareShortsVsLong

Short-form vs long-form performance

recommendUploadWindows

Best times to publish for engagement

Find what's working in any niche

Tool

What it does

discoverNicheTrends

Momentum, saturation, content gaps in any topic

exploreNicheCompetitors

Channel landscape and top performers

🎬 Media Assets

Download and manage video files locally

Tool

What it does

downloadAsset

Download video, audio, or thumbnails

listMediaAssets

Browse stored media files

removeMediaAsset

Clean up downloaded assets

extractKeyframes

Extract key frames from videos

mediaStoreHealth

Storage usage and diagnostics

Three-layer visual intelligence. Not transcript reuse.

Tool

What it does

indexVisualContent

Extract frames, run Apple Vision OCR + feature prints, Gemini frame descriptions, and Gemini semantic embeddings

searchVisualContent

Search visual frames using semantic embeddings + lexical matching. Returns actual image paths + timestamps as evidence

findSimilarFrames

Image-to-image frame similarity using Apple Vision feature prints

Three layers, all real:

  1. Apple Vision feature prints β€” image-to-image similarity (find frames that look alike)

  2. Gemini 2.5 Flash frame descriptions β€” natural language scene understanding per frame

  3. Gemini semantic embeddings — 768-dim embedding retrieval over OCR + description text for true text→visual search

What you always get back: frame path on disk, timestamp, source video URL/title, match explanation, OCR text, visual description.

What is NOT happening: no transcript embeddings are reused for visual search. This is a separate visual index.

πŸ’­ Comment Knowledge Base

Index and semantically search YouTube comments

Tool

What it does

importComments

Index a video's comments for search

searchComments

Natural language search over comment corpus

listCommentCollections

Browse comment collections

setActiveCommentCollection

Scope comment searches

clearActiveCommentCollection

Search all comment collections

removeCommentCollection

Delete a comment collection

πŸ₯ Diagnostics

Health checks and pre-flight validation

Tool

What it does

checkSystemHealth

Full system diagnostic report

checkImportReadiness

Validate before importing content


πŸ”‘ API Keys (Optional)

VidLens works without any API keys. Add them to unlock more capabilities:

Key

What it unlocks

Free?

How to get it

YOUTUBE_API_KEY

Better metadata, comment API, search via YouTube API

βœ… Free tier (10,000 units/day)

Google Cloud Console β†’ APIs β†’ Enable YouTube Data API v3 β†’ Credentials β†’ Create API Key

GEMINI_API_KEY

Higher-quality embeddings for semantic search (768d vs 384d)

βœ… Free tier

Google AI Studio β†’ Get API Key

⚠️ These are separate keys from separate Google services. A Gemini key will NOT work for YouTube API calls and vice versa. Create them independently.

# Configure via setup wizard
npx vidlens-mcp setup --youtube-api-key YOUR_YOUTUBE_KEY --gemini-api-key YOUR_GEMINI_KEY

# Or via environment variables
export YOUTUBE_API_KEY=your_youtube_key
export GEMINI_API_KEY=your_gemini_key

πŸ’» CLI

npx vidlens-mcp               # Start MCP server (stdio)
npx vidlens-mcp serve         # Start MCP server (explicit)
npx vidlens-mcp setup         # Auto-configure Claude Desktop + Claude Code
npx vidlens-mcp doctor        # Run diagnostics
npx vidlens-mcp version       # Print version
npx vidlens-mcp help          # Usage guide

Doctor - diagnose issues

npx vidlens-mcp doctor --no-live

Checks: Node.js version, yt-dlp availability, API key validation, data directory health, MCP client registration (Claude Desktop, Claude Code).


πŸ“± Works Everywhere β€” Desktop, Cowork, Phone

VidLens works across the full Claude ecosystem. Set it up once, use it everywhere.

Claude Desktop β€” Chat

The classic experience. Ask a question, get charts and analysis inline. Best for interactive research sessions.

Claude Desktop β€” Cowork Projects (March 2026)

Create a persistent research project with VidLens connected. Claude remembers context across sessions β€” last week's competitive research informs this week's analysis. Set up scheduled tasks that run automatically:

"Every Monday, search YouTube for new AI agent framework videos and compare to last week's findings."

Claude Dispatch β€” From Your Phone (March 2026)

Trigger any VidLens research from the Claude mobile app. Ask from your phone, Claude Desktop runs the tools locally, results come back to your pocket:

"Run my competitive research project β€” what new M5 Max content dropped this weekend?"

Claude Code β€” Remote Control

Start a Claude Code session with claude --remote-control, then continue from any browser or your phone at claude.ai/code. Full tool access, full context.

Note: Your Mac must be awake with Claude Desktop open for Cowork, Dispatch, and scheduled tasks to execute.


πŸ—οΈ Architecture

System Overview

How the Fallback Chain Works

Every tool that touches YouTube data uses the same resilience pattern:

Every response includes a provenance field telling you exactly which tier served the data and whether anything was partial. No silent degradation β€” you always know what happened.

Visual Search Pipeline

Visual search is not transcript reuse. It's a dedicated three-layer index:

Three layers, all real:

  1. Apple Vision feature prints β€” image-to-image similarity (find frames that look alike)

  2. Gemini Vision frame descriptions β€” natural language scene understanding per frame

  3. Gemini semantic embeddings β€” 768-dim retrieval over OCR + description text

Data Storage

Everything lives in a single directory. No external databases, no Docker, no infrastructure.

One directory. Portable. Back it up by copying. Delete it to start fresh.


πŸ“‹ Requirements

Requirement

Status

Notes

Node.js β‰₯ 22

Required

Uses node:sqlite β€” node --version to check

yt-dlp

Recommended

brew install yt-dlp - enables zero-config mode

ffmpeg

Optional

Needed for frame extraction and visual indexing

YouTube API key

Optional

Unlocks comments, better metadata

Gemini API key

Optional

Upgrades transcript embeddings and frame descriptions for visual search

macOS Apple Vision

Automatic on macOS

Powers native OCR and image similarity for visual search


πŸ”§ Troubleshooting

"Tool not found" in Claude Desktop

Fully quit Claude Desktop (⌘Q, not just close window) and reopen. MCP servers only load on startup.

"YOUTUBE_API_KEY not configured" warning

This is informational, not an error. VidLens works without it. Add a key only if you need comments/sentiment features.

"API_KEY_SERVICE_BLOCKED" error

Your API key has restrictions. Create a new unrestricted key in Google Cloud Console, or remove the API restriction from the existing key.

Gemini key doesn't work for YouTube API

These are separate services. You need a YouTube API key from Google Cloud Console AND a Gemini key from Google AI Studio. They are not interchangeable.

Build errors

npx vidlens-mcp doctor     # Run diagnostics
npx vidlens-mcp doctor --no-live  # Skip network checks

πŸ“„ License

MIT


Available Tools

41 tools
analyzePlaylistC

Expand and analyze a playlist in one call with partial success and aggregate benchmarks.

Inputs: playlistUrlOrId (required), analyses (required), maxVideos, commentsSampleSize, +2 more.

analyzeVideoSetC

Run multiple analyses across a video set with partial success, item-level errors, and provenance.

Inputs: videoIdsOrUrls (required), analyses (required), commentsSampleSize, transcriptMode, +1 more.

buildVideoDossierC

Build a one-shot video dossier with core metadata/transcript readiness, optionally extended with comments, sentiment, and provenance.

Inputs: videoIdOrUrl (required), commentSampleSize, includeComments, includeSentiment, +2 more.

checkImportReadinessC

Diagnose whether a video is importable, including transcript availability, sparse-transcript warnings, and yt-dlp/API issues.

Inputs: videoIdOrUrl (required), language, dryRun.

checkSystemHealthC

Check setup and provider health: yt-dlp, YouTube API, Gemini embeddings, and local storage.

Inputs: runLiveChecks, dryRun.

clearActiveCollectionA

Clear the active collection so transcript search fans back out across all collections.

Inputs: no named parameters.

clearActiveCommentCollectionB

Clear the active comment collection so comment search fans back out across all comment collections.

Inputs: no named parameters.

compareShortsVsLongC

Compare recent Shorts vs long-form performance for a channel and suggest a format mix.

Inputs: channelIdOrHandleOrUrl (required), lookbackDays, dryRun.

discoverNicheTrendsA

Discover what's trending in a niche right now. Returns top-performing and recent videos, momentum signals (accelerating/steady/decelerating), saturation analysis, content gap opportunities, keyword patterns, and format breakdown. Grounded in YouTube search data with honest limitations disclosed.

Inputs: niche (required), regionCode, maxResults, lookbackDays, +1 more.

downloadAssetA

Download a YouTube video, audio track, or thumbnail to local storage. Returns asset manifest entry with file path. Does NOT perform visual indexing β€” this is honest file storage.

Inputs: videoIdOrUrl (required), format (required), maxSizeMb.

expandPlaylistC

Expand a playlist into individual videos for downstream analysis and batch workflows.

Inputs: playlistUrlOrId (required), maxVideos, includeVideoMeta, dryRun.

exploreNicheCompetitorsB

Discover active channels in a niche by analyzing who ranks in YouTube search results. Returns channel-level stats, top videos, and a landscape summary. Useful for competitive reconnaissance before entering a niche.

Inputs: niche (required), regionCode, maxChannels, dryRun.

exploreYouTubeA

ALWAYS use this tool FIRST when the user wants to find, discover, or explore YouTube videos. Do NOT use web search for YouTube video discovery β€” use this tool instead. Searches YouTube directly with intelligent multi-query ranking and parallel enrichment. Returns ranked videos with transcript summaries, key moments, and readiness for follow-up. IMPORTANT: When results contain benchmark scores, statistics, or comparisons, ALWAYS create visual charts and infographics (bar charts, comparison tables) from the data immediately β€” do not wait for the user to ask. Use 'specific' mode to find one best video. Use 'explore' for topic discovery across creators. Depth: 'quick' for metadata, 'standard' for key moments + transcript summaries, 'deep' for background indexing.

Inputs: query, searches, mode, creator, +8 more.

extractKeyframesA

Extract keyframe images from a locally downloaded video at regular intervals using ffmpeg. Requires the video to be downloaded first via downloadAsset. Does NOT do visual search or classification β€” produces raw frame images.

Inputs: videoIdOrUrl (required), intervalSec, maxFrames, imageFormat, +1 more.

findSimilarFramesC

Find frames that visually look like a reference frame using Apple Vision image feature prints. Accepts a frame assetId or a direct framePath and returns image-backed matches.

Inputs: assetId, framePath, videoIdOrUrl, maxResults, +2 more.

findVideosC

Search YouTube videos by intent. Returns compact ranked results with provenance and engagement hints.

Inputs: query (required), maxResults, order, regionCode, +5 more.

importCommentsB

Import a video's comments into the local comment knowledge base for semantic search. Fetches comments via the existing comment pipeline and indexes them for searchComments.

Inputs: videoIdOrUrl (required), collectionId, maxTopLevel, includeReplies, +5 more.

importPlaylistC

Import a playlist into the local transcript knowledge base for semantic search in Claude Desktop.

Inputs: playlistUrlOrId (required), collectionId, maxVideos, chunkStrategy, +10 more.

importVideosC

Import one or more videos into a local transcript collection for later semantic search.

Inputs: videoIdsOrUrls (required), collectionId, chunkStrategy, chunkSizeSec, +9 more.

indexVisualContentB

Build a real visual index for a video using extracted frames, Apple Vision OCR, Apple Vision feature prints, and optional Gemini frame descriptions. Returns frame evidence with local image paths.

Inputs: videoIdOrUrl (required), intervalSec, maxFrames, imageFormat, +7 more.

inspectChannelC

Inspect a channel with summary stats and posting cadence heuristics.

Inputs: channelIdOrHandleOrUrl (required), dryRun.

inspectVideoC

Inspect a single video with compact metadata, normalized ratios, and transcript availability.

Inputs: videoIdOrUrl (required), includeTranscriptMeta, includeEngagementRatios, dryRun.

listChannelCatalogC

List a channel's recent catalog in compact creator-analysis shape.

Inputs: channelIdOrHandleOrUrl (required), maxResults, sortBy, includeShorts, +3 more.

listCollectionsB

List local transcript collections, active search focus, and indexed video/chunk counts.

Inputs: includeVideoList.

listCommentCollectionsC

List local comment collections, active search focus, and indexed comment counts.

Inputs: includeVideoList.

listMediaAssetsC

List locally stored media assets. Filter by video or kind. Shows file paths, sizes, and manifest metadata.

Inputs: videoIdOrUrl, kind, limit.

measureAudienceSentimentC

Heuristic audience sentiment analysis from comments with themes, risk signals, and quote samples.

Inputs: videoIdOrUrl (required), sampleSize, includeThemes, includeRepresentativeQuotes, +1 more.

mediaStoreHealthA

Check health of the local media store: disk usage, asset counts, ffmpeg/yt-dlp availability.

Inputs: no named parameters.

readCommentsC

Read top-level comments with optional replies and structured provenance.

Inputs: videoIdOrUrl (required), maxTopLevel, includeReplies, maxRepliesPerThread, +3 more.

readTranscriptC

Read transcript in summary, key moments, chapters, or paginated full mode with long-video safeguards.

Inputs: videoIdOrUrl (required), language, mode, includeTimestamps, +4 more.

recommendUploadWindowsC

Recommend upload windows from recent publishing history for a given timezone.

Inputs: channelIdOrHandleOrUrl (required), timezone (required), lookbackDays, dryRun.

removeCollectionB

Delete a local transcript collection and its search index.

Inputs: collectionId (required).

removeCommentCollectionC

Delete a local comment collection and its search index.

Inputs: collectionId (required).

removeMediaAssetB

Remove stored media assets. Specify assetId to remove one, or videoIdOrUrl to remove all assets for a video.

Inputs: assetId, videoIdOrUrl, deleteFiles.

researchTagsAndTitlesC

Research title structures, keywords, and tag patterns around a seed topic.

Inputs: seedTopic (required), regionCode, language, maxExamples, +1 more.

scoreHookPatternsC

Heuristically score first-30-second hooks across one or more videos.

Inputs: videoIdsOrUrls (required), hookWindowSec, dryRun.

searchCommentsB

Search imported comment collections with ranked results. Returns matching comments with author, like count, and relevance score. Uses active comment collection by default.

Inputs: query (required), collectionId, maxResults, minScore, +2 more.

searchTranscriptsC

Search imported transcript-text collections with active-collection focus by default and return ranked timestamped chunks.

Inputs: query (required), collectionId, maxResults, minScore, +2 more.

searchVisualContentA

Search the actual visual content of a video or your indexed frame library. Uses Apple Vision OCR, optional Gemini frame descriptions, and optional Gemini semantic embeddings. Always returns frame/image evidence with timestamps.

Inputs: query (required), videoIdOrUrl, maxResults, minScore, +10 more.

setActiveCollectionB

Set the default collection that transcript search should focus on when collectionId is omitted.

Inputs: collectionId (required).

setActiveCommentCollectionA

Set the default comment collection that searchComments should focus on when collectionId is omitted.

Inputs: collectionId (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 41 tools

    Disambiguation3/5

    There is significant functional overlap between tools, causing potential confusion. For example, 'analyzePlaylist', 'expandPlaylist', and 'importPlaylist' all handle playlists but with unclear distinctions, and 'findVideos' vs 'exploreYouTube' both search YouTube with overlapping purposes. However, detailed descriptions help differentiate some tools, preventing complete ambiguity.

    Naming Consistency4/5

    Most tools follow a clear verb_noun naming pattern (e.g., 'analyzePlaylist', 'checkSystemHealth', 'downloadAsset'), which is consistent and predictable. A few tools deviate slightly (e.g., 'exploreYouTube' uses a proper noun, 'findSimilarFrames' uses an adjective), but these are minor exceptions that don't disrupt overall readability.

    Tool Count2/5

    With 41 tools, the count is excessive for the server's purpose of YouTube video analysis and management. Many tools could be consolidated (e.g., multiple playlist-related tools) or represent overly granular operations, making the surface unwieldy and likely to overwhelm agents or users.

    Completeness5/5

    The tool set comprehensively covers the domain of YouTube video analysis, including discovery, import, transcription, comment handling, visual indexing, search, and management. It provides full lifecycle coverage from video retrieval to deep analysis, with no apparent gaps that would hinder agent workflows.

    Related MCP Connectors