tube-bridge
A self-hosted MCP server for YouTube research and local semantic transcript corpora.
Search videos and channels, get trending videos, channel uploads, playlists, and video/channel metadata.
Retrieve transcripts with optional timestamps, list subtitle languages, and fetch top-level comments when a YouTube API key is configured.
Extract one ephemeral JPEG frame near a timestamp (requires ffmpeg).
Create, add to, semantically search, list, and delete local transcript corpora using local embeddings.
Read runtime documentation and known limitations; 14 of 17 tools need no YouTube API key.
Provides tools for searching YouTube videos, retrieving video metadata and transcripts, exploring channels, playlists, and comments, and building semantic search corpora over video transcripts.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tube-bridge what are the latest videos from Veritasium?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
tube-bridge
Self-hosted YouTube research for AI agents.
Search videos and channels, read transcripts and comments, extract timestamped frames, and build private semantic-search corpora — through 17 MCP tools.
14 of 17 tools need no YouTube API key.
Local-first corpus: transcripts, vectors, and indexes stay on your machine.
Useful research output: titles, similarity scores, canonical video URLs, and timestamp links.
One tool for one frame: return visual evidence near a transcript finding without keeping media files.
Self-hosted and MIT: no account, hosted intermediary, managed storage, or vendor lock-in.
Thanks to everyone already using tube-bridge. If it saves you time, consider starring the repository — it helps others discover the project and signals that publishing more work like this is worthwhile.
Connect in a minute
The simplest setup uses uvx, which runs the published PyPI package in an isolated environment:
uvx tube-bridgeNormally your MCP client launches that command for you. Choose your client below.
tube-bridge requires Python 3.12 or newer. An API key is optional.ffmpeg is needed only for youtube_get_frame, and the first embedding operation may download the local model.
Claude Desktop
Open Settings → Developer → Edit Config and add:
{
"mcpServers": {
"tube-bridge": {
"command": "uvx",
"args": ["tube-bridge"]
}
}
}Restart Claude Desktop after saving the configuration.
Claude Code
claude mcp add --scope user tube-bridge -- uvx tube-bridgeCursor
Create .cursor/mcp.json in your project, or add the server to your user-level MCP configuration:
{
"mcpServers": {
"tube-bridge": {
"command": "uvx",
"args": ["tube-bridge"]
}
}
}VS Code
Create .vscode/mcp.json:
{
"servers": {
"tube-bridge": {
"type": "stdio",
"command": "uvx",
"args": ["tube-bridge"]
}
}
}Codex CLI
codex mcp add tube-bridge -- uvx tube-bridgeRelated MCP server: yt
Pi package
Pi can load the package-relative adapter and the canonical tube-bridge-research skill from the same Git source:
python3 -m pip install tube-bridge==1.1.7
pi install git:github.com/TheWhiteWater/tube-bridge@v1.1.7
pi listThis registers one status tool plus all 17 MCP tools with the tube_bridge_ prefix. The adapter reads the existing plugin.json and mcp.json, launches only the local stdio runtime, preserves bounded text and image content, and forwards only an allowlisted child-process environment.
The Pi package manager installs the Node adapter dependency but does not install Python or ffmpeg. Ensure the python3 visible to Pi is Python 3.12+ with the tube-bridge dependencies installed; install ffmpeg separately to use youtube_get_frame. By default, Pi-managed state lives under the platform data directory; set TUBE_BRIDGE_PI_DATA to move that root. An explicit TUBE_BRIDGE_CACHE still takes precedence for the runtime databases. The optional live frame gate is /tube-bridge-selftest frame.
Remove the package with:
pi remove git:github.com/TheWhiteWater/tube-bridge@v1.1.7If a desktop client cannot find uvx, replace "uvx" with the absolute path returned by which uvx on macOS/Linux or where.exe uvx on Windows.
Try the complete research workflow
Ask your agent:
Search YouTube for recent videos about local-first AI agents. Read the transcript of the strongest result, add it to a corpus named
local-agents, find the section discussing memory, return the timestamped source link, and extract a frame from that moment.
The agent can complete that request with this tool sequence:
youtube_search(query="local-first AI agents", order="date")
youtube_get_transcript(url="https://www.youtube.com/watch?v=VIDEO_ID", with_timestamps=true)
corpus_create(corpus_id="local-agents", label="Local-first AI Agents")
corpus_add(corpus_id="local-agents", url="https://www.youtube.com/watch?v=VIDEO_ID")
corpus_search(corpus_id="local-agents", query="memory architecture")
youtube_get_frame(url="https://www.youtube.com/watch?v=VIDEO_ID", timestamp_ms=FOUND_TIME_MS)Add more videos with corpus_add, then use corpus_search to search across all of their transcripts at once.
Tools
Tool | YouTube API key | What it does |
| Optional | Search videos with date, channel, duration, and ordering filters |
| Optional | Get title, duration, views, channel, description, and tags |
| Optional | Get currently trending videos |
| No | Get recent uploads from a channel URL or |
| No | Get videos from a playlist |
| No | Get a transcript, optionally with |
| No | Return one ephemeral JPEG near an integer-millisecond timestamp |
| No | List manual and auto-generated subtitle tracks |
| Required | Get top-level comments with likes and reply counts |
| Required | Search channels and filter by subscriber count |
| Required | Get channel statistics, country, and keywords |
| No | Create a named local corpus |
| No | Fetch, chunk, and locally embed a video transcript |
| No | Semantically search a corpus with timestamped results |
| No | List corpora with video and chunk counts |
| No | Permanently delete a corpus and its vectors |
| No | Read runtime documentation and known limitations |
No means no YouTube Data API key is needed; network access to YouTube may still be required. Search, video information, and trending work without a key through yt-dlp and upgrade to Data API v3 when a key is configured.
Optional YouTube Data API key
A YouTube Data API v3 key unlocks comments, channel search, and channel details. It also improves search, video information, and trending reliability.
Create a key in Google Cloud Console, enable YouTube Data API v3, and expose it to the process launching tube-bridge:
export YOUTUBE_API_KEY="your-key"Keep keys out of committed MCP configuration files. Use your client's secret/environment support where available.
Local semantic corpus
Corpus storage and embedding inference are local to the machine running tube-bridge.
Storage: SQLite plus sqlite-vec in
~/.tube_bridge/corpus.dbEmbeddings: BGE-small-en-v1.5 through fastembed
Chunking: 80-second windows with 20-second overlap
Ranking: overlap deduplication and source-aware per-video limits
Results: similarity score, time span, video title, canonical URL, and timestamp URL
Set TUBE_BRIDGE_CACHE to move both corpus and cache databases:
export TUBE_BRIDGE_CACHE="/path/to/tube-bridge-data"The embedding model may be downloaded on first use. After the assets are available, embedding inference does not require an external model API.
Frame extraction
youtube_get_frame requires ffmpeg on PATH; the Docker image already includes it.
Each call downloads a short temporary section around timestamp_ms, returns one bounded JPEG as MCP ImageContent, and removes the temporary media before returning. It does not create a frame or clip library.
Other ways to run
Persistent PyPI installation
pip install tube-bridge
tube-bridge # stdio
tube-bridge --http # Streamable HTTP on port 8080Docker
docker run --rm -p 8080:8080 ghcr.io/thewhitewater/tube-bridge:latestThe health endpoint is http://localhost:8080/health; the Streamable HTTP endpoint is http://localhost:8080/mcp.
The image is published for linux/amd64 and linux/arm64; Docker pulls the right one automatically. On a Raspberry Pi, use a 64-bit OS: 32-bit Raspberry Pi OS is not supported. Every release runs the image on native arm64 CI runners, but it has not been tested on physical Raspberry Pi hardware yet.
Official MCP Registry
Registry name: io.github.TheWhiteWater/tube-bridge
Registry-aware clients can install the PyPI distribution with uvx and launch the stdio server without a hosted intermediary.
Remote HTTP configuration
For an HTTP instance you operate:
{
"mcpServers": {
"tube-bridge": {
"type": "http",
"url": "https://your-host.example/mcp"
}
}
}Protect remote MCP routes by setting a server-side Bearer key:
export TUBE_BRIDGE_AUTH_KEY="choose-a-long-random-value"
tube-bridge --httpThen configure a header-capable client:
{
"mcpServers": {
"tube-bridge": {
"type": "http",
"url": "https://your-host.example/mcp",
"headers": {
"Authorization": "Bearer <your-key>"
}
}
}
}/health remains public. /mcp, /sse, and /messages require the Bearer key when TUBE_BRIDGE_AUTH_KEY is set. Legacy SSE is available at /sse for clients that still need it.
Environment variables
Variable | Required | Purpose |
| No | Enables the 3 API-only tools and upgrades supported discovery calls |
| No | Routes yt-dlp and transcript requests through an HTTP(S) or SOCKS proxy |
| No | Changes the directory containing |
| No | Protects self-hosted HTTP MCP routes with a static Bearer token |
How it works
MCP client
│
├── discovery and metadata ── Data API v3 (when configured)
│ └─ yt-dlp fallback
├── transcripts ───────────── youtube-transcript-api
├── timestamped frames ────── yt-dlp + ffmpeg → ephemeral JPEG
└── semantic corpus ───────── SQLite + sqlite-vec + local fastembedstdio is recommended for local clients;
Streamable HTTP is available at
/mcpfor self-hosted remote use;successful fallback responses keep their normal schemas;
controlled failures use typed MCP errors with stable
code,source, andretryablefields;cache and corpus databases are separate and remain operator-owned.
Agent Plugin preview
GitHub Releases include tube-bridge-agent-plugin-<version>.zip, containing:
the local stdio MCP configuration;
the
tube-bridge-researchskill;research templates and source-evaluation guidance.
Agent Plugins v1 does not standardize dependency installation. Install Python 3.12+, ffmpeg, and the package dependencies in the environment used by the plugin host. The bundle contains no credentials.
Known limitations
YouTube can restrict anonymous yt-dlp and transcript requests, especially from cloud-hosting IP ranges.
A Data API key improves discovery and metadata reliability but does not replace transcript access.
Initial local embedding-model setup may require network access and additional disk space.
tube-bridge is self-hosted software; it does not provide accounts, public hosted access, managed storage, or an SLA.
If YouTube blocks requests from your network, set TUBE_BRIDGE_PROXY. Keep proxy credentials in environment variables rather than committed configuration.
Development
git clone https://github.com/TheWhiteWater/tube-bridge.git
cd tube-bridge
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements-release.txt
pip install --no-deps -e .
pip install pytest pytest-asyncio pytest-mock build twine
python -m pytest tests -qpython test_tools.py is an optional live YouTube smoke test. The deterministic test suite does not call YouTube.
See CONTRIBUTING.md to contribute. Security reports should follow SECURITY.md.
License
MIT — see LICENSE.
Available Tools
17 toolscorpus_addADestructive
Fetch a video's transcript, chunk it, and store local embeddings in an existing corpus. Use this after corpus_create; it skips an already-indexed video by default. force_reembed=true deletes and replaces that video's existing local chunks and vectors. This modifies local corpus data and may contact YouTube; returns indexing status and chunk count.
Inputs: url (required), corpus_id (required), force_reembed.
corpus_createAIdempotent
Create a named corpus for semantic search over transcripts. Each corpus uses a fixed embedding model.
Inputs: corpus_id (required), label.
corpus_deleteADestructiveIdempotent
Delete a corpus and all its chunks/vectors permanently.
Inputs: corpus_id (required).
corpus_listARead-onlyIdempotent
List all available corpora with chunk and video counts.
Inputs: no named parameters.
corpus_searchARead-onlyIdempotent
Semantic search within a corpus. Deduplicates overlapping windows, limits source domination, and returns titles plus timestamp URLs.
Inputs: query (required), corpus_id (required), top_k.
tube_bridge_helpARead-onlyIdempotent
Get tube-bridge documentation: available tools, architecture, known limitations, API key setup.
Inputs: no named parameters.
youtube_get_available_languagesARead-onlyIdempotent
Available subtitle languages for a video. Shows manual vs auto-generated.
Inputs: url (required).
youtube_get_channel_infoARead-onlyIdempotent
Detailed channel metadata: subscribers, views, videos, country, keywords. Requires YOUTUBE_API_KEY.
Inputs: channel_id (required).
youtube_get_channel_videosARead-onlyIdempotent
List up to limit recent uploads from a known YouTube channel URL or @handle. Use this for channel browsing, not keyword search or channel metadata. Read-only and keyless; returns normalized channel metadata plus video records. Empty results include a warning when the channel is missing or has no uploads.
Inputs: channel_url (required), limit.
youtube_get_commentsARead-onlyIdempotent
Retrieve up to max_results top-level comments for a known YouTube video. Use this for audience reactions, not video metadata or transcripts. Read-only and requires YOUTUBE_API_KEY; returns structured comment records. Calls may fail when comments are disabled, the video is unavailable, or Data API quota is exhausted.
Inputs: url (required), max_results.
youtube_get_frameARead-onlyIdempotent
Extract one ephemeral JPEG near an integer-millisecond timestamp. Returns metadata plus MCP ImageContent; accuracy is best-effort at a decoded frame boundary.
Inputs: url (required), timestamp_ms (required), max_width.
youtube_get_playlistARead-onlyIdempotent
List up to limit videos from a known YouTube playlist URL in upstream order. Use this for playlist contents, not channel uploads or keyword search. Read-only and keyless; returns playlist metadata plus ordered video records. Results are bounded and may fail when the playlist is private, unavailable, or blocked upstream.
Inputs: playlist_url (required), limit.
youtube_get_transcriptARead-onlyIdempotent
Transcript/subtitles of a YouTube video. Uses the original/default language; manual > ASR within that language.
Inputs: url (required), lang, with_timestamps.
youtube_get_trendingARead-onlyIdempotent
List up to limit currently trending YouTube videos. Use this for broad discovery, not keyword search. Read-only; uses Data API v3 when YOUTUBE_API_KEY is set and otherwise a keyless yt-dlp fallback. Returns source metadata and video records; results can change over time and depend on upstream availability.
Inputs: limit.
youtube_get_video_infoARead-onlyIdempotent
Detailed metadata for a YouTube video: title, duration, views, channel, description, tags.
Inputs: url (required).
youtube_searchARead-onlyIdempotent
Search YouTube videos. Uses Data API v3 when YOUTUBE_API_KEY is set, falls back to yt-dlp. Filters: date range, channel, duration, order.
Inputs: query (required), limit, order, channel_id, +3 more.
youtube_search_channelsARead-onlyIdempotent
Search YouTube channels by name/topic. Returns subscriber counts, video counts, country. Requires YOUTUBE_API_KEY.
Inputs: query (required), limit, order, max_subscribers, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Every tool addresses a distinct resource or action: searching channels vs. videos, fetching channel metadata vs. channel uploads, video metadata vs. transcript vs. comments vs. frames, and clear corpus operations. Even similar-looking tools like youtube_get_channel_info and youtube_get_channel_videos are unambiguous due to explicit descriptions.
Most tools follow a predictable pattern: youtube_<verb>_<resource> or corpus_<verb>. Minor deviations include youtube_get_trending (no resource noun) and tube_bridge_help (namespace mismatch), but the overall structure remains readable and consistent.
With 17 tools covering YouTube data retrieval, transcript processing, and semantic corpus management, the count is slightly high but justified by the broad scope. Each tool has a clear purpose, and the split between YouTube-facing and corpus-facing tools keeps the set manageable.
The tool set covers the full YouTube read-only surface: search, channel/video/playlist metadata, transcripts, frames, languages, comments, and trending. Corpus tools provide create/add/search/list/delete, and force_reembed covers updates. The help tool fills documentation gaps, so no critical operations are missing.
Maintenance
Related MCP Connectors
An MCP server that gives any LLM or agent clean YouTube transcripts on demand: a single video, a whole channel, or a playlist, plus AI cleanup of auto-generated captions. API-key auth, credit-based, same backend as the public v1 API. Get a free API key with 25 free credits at youtubetranscriptdownload.com/account.
Your agent needs to find video — which channels own a topic, which videos rank for a phrase, what exists in a given country and language. **What you can ask for** • "Which videos rank for 'rag pipeline tutorial' in the US this month?" • "Find channels publishing about MCP, sorted by relevance." • "What playlists cover this subject in Japanese?" • "Search videos uploaded this week only." **How to use it** Point any MCP client at https://mcp.aisa.one/youtube-search/mcp and sign in with OAuth — there is no key to create or paste. One search tool covering videos, channels and playlists, narrowed by country, language, upload date, duration and sort order. **It is also a door to the rest** The same login reaches 26 sources and 580+ operations. Find the video here, then ask the same agent what the channel's site traffic is or what the same phrase does in Google — without adding a second server. **What it costs** Finding and inspecting an operation is free. Running one is billed per call at API prices, with no seat and no monthly minimum, and every call takes max_price_usd so an agent cannot overspend by accident. **Where else it reaches** https://mcp.aisa.one/social/mcp for X plus Instagram, Reddit, Pinterest and YouTube; https://mcp.aisa.one/gtm/mcp for those plus Similarweb and Apollo.
YouTube transcripts, search, channel/playlist listings and upload tracking for AI agents.
Real-time YouTube transcripts, comments, channels & video search MCP. Local npx or hosted OAuth.
Related MCP Servers
- AlicenseBqualityDmaintenanceAn MCP server that provides AI assistants with powerful tools to interact with YouTube, including video searching, transcript extraction, comment retrieval, and more.819Apache 2.0
- AlicenseNot gradedqualityNot gradedmaintenanceAn 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-
- AlicenseAqualityBmaintenanceMCP server that provides YouTube video data to AI agents, supporting search, metadata, comments, and transcripts without an API key.660 npmISC
- AlicenseAqualityDmaintenanceMCP server that lets AI agents search YouTube and fetch transcripts.23MIT