vidlens-mcp

🔍 What is VidLens?

VidLens is a Model Context Protocol server that gives AI agents deep, reliable access to YouTube. Not just transcripts - full intelligence: sentiment analysis, trend discovery, semantic search, media assets, creator analytics, and image-backed visual search.

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.

🎯 Core Capabilities

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

"Find every mention of gradient descent across 50 Stanford CS lectures"

"What did the instructor say about backpropagation in any of these videos?"

👁️ 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. Three layers: Apple Vision feature prints for image similarity, Gemini frame descriptions for scene understanding, and semantic embeddings for text→visual search.

"Find the frame where he draws the system architecture diagram"

"Show me every slide that mentions 'transformer architecture'"

📊 Intelligence Layer — Not Just Data

Sentiment analysis with themes and risk signals. Niche trend discovery with momentum and saturation scoring. Content gap detection. Hook pattern analysis. Upload timing recommendations. The LLM does the thinking — VidLens gives it the right data.

"What's the audience sentiment on this video? Any risk signals?"

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

⚡ Zero Config, Always Works

No API key needed to start. Three-tier fallback chain on every tool: YouTube API → yt-dlp → page extraction. Nothing breaks when quota runs out. Keys are optional power-ups, not requirements.

🎬 Full Media Pipeline

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

⚡ 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

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

"Search this video's visuals for the whiteboard architecture diagram and show me the frame evidence"

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

"Build a complete dossier for this video — metadata, transcript, sentiment, hooks, everything"

"What's the audience sentiment on this video? Any risk signals?"

"Get the transcript of this video: https://youtube.com/watch?v=dQw4w9WgXcQ"

🧰 Tools - 40 across 9 modules

📺 Core - Video & Channel Intelligence

Always available, no API key needed

🔎 Knowledge Base - Semantic Search

Index transcripts and search across them with natural language

💬 Sentiment & Analysis

Understand what audiences think and feel

🎯 Creator Intelligence

Insights for content strategy

📈 Discovery & Trends

Find what's working in any niche

🎬 Media Assets

Download and manage video files locally

🖼️ Visual Search

Three-layer visual intelligence. Not transcript reuse.

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

🏥 Diagnostics

Health checks and pre-flight validation

🔑 API Keys (Optional)

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

⚠️ 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).

🏗️ 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

🔧 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

GitHub · npm · Model Context Protocol