Apache-2.0 · FastMCP · 10 MCP tools

Search, understand & cite
Public YouTube Videos

TubeLens OSS connects AI agents directly to YouTube metadata and Google Gemini video understanding. Zero local media downloads — public video URLs are processed natively on Google Cloud via Part.from_uri() with timestamped evidence citations.

🔒 Zero Local Downloads (Part.from_uri) ⚡ Stateless by default — no disk cache, no DB 🌐 Streamable HTTP + SSE 🔍 Channel & Catalog Discovery

Watch Claude Research a Creator via MCP

An AI agent connects to TubeLens deployed on Cloud Run, chaining 5 MCP tool calls to go from a question to verified, cited intelligence.

Claude
MCP Connected
tubelens-mcp-xxxxxxx.run.app/mcp
10 tools
Ready

10 Video Intelligence & Research Tools

Turn unstructured YouTube videos into queryable, comparable, verifiable knowledge objects with zero local media downloads.

youtube_extract_recommendations Decisions

Extracts explicit and implicit recommendations, actions, stance, conviction, risks, alternatives, and timestamped citations.

youtube_extract_claims Fact Check

Deconstructs videos into discrete falsifiable claims vs opinions, with categorization and independent verification guidance.

youtube_evaluate_fit Personalization

Scores video relevance (0–100) against user constraints and outputs matching points, conflicting caveats, and tailored action items.

youtube_compare_videos Synthesis

Synthesizes 2 to 5 videos to reveal consensus, a dimensional disagreement matrix with root causes, and a decision playbook.

youtube_ask_video Ephemeral Q&A

Answers deep, complex questions directly from video content with structured timestamped evidence citations.

youtube_analyze_video Overview

Generates analytical summaries (500–800 words), key topics, short attributed excerpts, and timestamped topic indexes.

youtube_resolve_channel Discovery

Resolves creator handles (@handle), channel names, or vanity URLs into canonical YouTube Channel IDs.

youtube_list_channel_videos Catalog

Browses, filters, and paginates through a creator's uploaded video catalog with keyword search and duration filters.

youtube_list_playlist_videos Playlist

Enumerates and paginates through all videos contained in any public or unlisted YouTube playlist.

youtube_get_videos Batch Metadata

Batch retrieves detailed metadata (tags, view counts, duration, publication date) for up to 50 video IDs in one request.

Run in 3 Steps

Spin up your local TubeLens MCP server in seconds using uv.

# 1. Clone the repository
git clone https://github.com/mbettan/tubelens-oss.git
cd tubelens-oss

# 2. Copy and configure environment variables
cp .env.example .env
# Edit .env with your GOOGLE_CLOUD_PROJECT and YOUTUBE_API_KEY

# 3. Sync dependencies and run server locally
uv sync
uv run python -m src.server

Connect Any AI Agent

Plug TubeLens directly into Claude Desktop, Gemini CLI, Cursor, or ChatGPT Actions.

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "tubelens": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.server"],
      "cwd": "/path/to/tubelens-oss",
      "env": {
        "GOOGLE_CLOUD_PROJECT": "your-project-id",
        "YOUTUBE_API_KEY": "your-youtube-api-key",
        "AUTH_MODE": "none"
      }
    }
  }
}

Add with the Antigravity CLI or Google AI SDK:

antigravity mcp add tubelens \
  --command "uv run python -m src.server" \
  --cwd "/path/to/tubelens-oss" \
  --env GOOGLE_CLOUD_PROJECT=your-project-id \
  --env YOUTUBE_API_KEY=your-youtube-api-key \
  --env AUTH_MODE=none

Point Custom GPT Actions to the remote MCP Streamable HTTP endpoint:

# OpenAPI 3.1 endpoint for Custom GPTs
url: "https://your-cloud-run-url.run.app/mcp"
auth:
  type: "bearer"
  token: "YOUR_MCP_API_KEY"

Deploy to Google Cloud Run with Cloud Build:

gcloud builds submit --config=cloudbuild.yaml \
  --substitutions=_REGION="us-central1",_SERVICE_NAME="tubelens-mcp"

Common Questions & Architecture

Everything you need to know about TubeLens data privacy, compliance, and deployment.

Does TubeLens OSS download YouTube videos to local disk?

No. TubeLens OSS performs zero local media downloads. Public video URLs are passed directly to Google Gemini via Google Cloud's Part.from_uri() multimodal engine, ensuring no video or audio files are written to local storage.

Does TubeLens store or cache transcripts in a database?

No. TubeLens OSS operates with a 100% live and stateless architecture. There is zero disk caching and zero database persistence. Every request retrieves fresh data directly from the YouTube Data API v3 and Google Gemini.

How does the automated model fallback ladder work?

TubeLens automatically catches transient errors (429 Rate Limit, Quota Exceeded, 404, or DeadlineExceeded) and seamlessly switches from primary model (gemini-3.7-flash) to fallback model (gemini-3.6-flash) with zero interruption to the AI client.

Is TubeLens OSS compliant with YouTube Terms of Service?

TubeLens is designed for compliance: it uses only the official YouTube Data API v3 for metadata and passes public URLs to Google Cloud for analysis. It downloads, stores, and redistributes nothing. You remain responsible for your own use — see LEGAL.md.

Can I deploy TubeLens OSS to Google Cloud Run?

Yes! A production-ready Dockerfile and cloudbuild.yaml are included in the repository. You can deploy a scalable, stateless Streamable HTTP FastMCP endpoint to Cloud Run with a single command.

What does it cost to run, and what are the quota limits?

TubeLens itself is free (Apache-2.0). You pay Google for what you use: the YouTube Data API v3 default quota is 10,000 units/day — a videos.list call costs 1 unit, a search.list costs 100 — and Gemini multimodal inference is billed per input token, where video is tokenized at roughly 300 tokens per second of footage at default resolution. A 20-minute video analysis is typically a few cents. The server surfaces quota usage in every tool response so your agent can budget.