Extracts explicit and implicit recommendations, actions, stance, conviction, risks, alternatives, and timestamped citations.
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.
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.
10 Video Intelligence & Research Tools
Turn unstructured YouTube videos into queryable, comparable, verifiable knowledge objects with zero local media downloads.
Deconstructs videos into discrete falsifiable claims vs opinions, with categorization and independent verification guidance.
Scores video relevance (0–100) against user constraints and outputs matching points, conflicting caveats, and tailored action items.
Synthesizes 2 to 5 videos to reveal consensus, a dimensional disagreement matrix with root causes, and a decision playbook.
Answers deep, complex questions directly from video content with structured timestamped evidence citations.
Generates analytical summaries (500–800 words), key topics, short attributed excerpts, and timestamped topic indexes.
Resolves creator handles (@handle), channel names, or vanity URLs into canonical YouTube Channel IDs.
Browses, filters, and paginates through a creator's uploaded video catalog with keyword search and duration filters.
Enumerates and paginates through all videos contained in any public or unlisted YouTube playlist.
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.