tube-bridge
Advanced tools
Tube Bridge — YouTube MCP server for AI agents. 17 tools: search, transcripts, frames, semantic corpus, comments. Zero keys + optional API v3.
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.
The simplest setup uses uvx, which runs the published PyPI package in an isolated environment:
uvx tube-bridge
Normally your MCP client launches that command for you. Choose your client below.
[!NOTE] tube-bridge requires Python 3.12 or newer. An API key is optional.
ffmpegis needed only foryoutube_get_frame, and the first embedding operation may download the local model.
Open Settings → Developer → Edit Config and add:
{
"mcpServers": {
"tube-bridge": {
"command": "uvx",
"args": ["tube-bridge"]
}
}
}
Restart Claude Desktop after saving the configuration.
claude mcp add --scope user tube-bridge -- uvx tube-bridge
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"]
}
}
}
Create .vscode/mcp.json:
{
"servers": {
"tube-bridge": {
"type": "stdio",
"command": "uvx",
"args": ["tube-bridge"]
}
}
}
codex mcp add tube-bridge -- uvx tube-bridge
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.6
pi install git:github.com/TheWhiteWater/tube-bridge@v1.1.6
pi list
This 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.6
If 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.
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.
| Tool | YouTube API key | What it does |
|---|---|---|
youtube_search | Optional | Search videos with date, channel, duration, and ordering filters |
youtube_get_video_info | Optional | Get title, duration, views, channel, description, and tags |
youtube_get_trending | Optional | Get currently trending videos |
youtube_get_channel_videos | No | Get recent uploads from a channel URL or @handle |
youtube_get_playlist | No | Get videos from a playlist |
youtube_get_transcript | No | Get a transcript, optionally with [MM:SS] timestamps |
youtube_get_frame | No | Return one ephemeral JPEG near an integer-millisecond timestamp |
youtube_get_available_languages | No | List manual and auto-generated subtitle tracks |
youtube_get_comments | Required | Get top-level comments with likes and reply counts |
youtube_search_channels | Required | Search channels and filter by subscriber count |
youtube_get_channel_info | Required | Get channel statistics, country, and keywords |
corpus_create | No | Create a named local corpus |
corpus_add | No | Fetch, chunk, and locally embed a video transcript |
corpus_search | No | Semantically search a corpus with timestamped results |
corpus_list | No | List corpora with video and chunk counts |
corpus_delete | No | Permanently delete a corpus and its vectors |
tube_bridge_help | 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.
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.
Corpus storage and embedding inference are local to the machine running tube-bridge.
~/.tube_bridge/corpus.dbSet 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.
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.
pip install tube-bridge
tube-bridge # stdio
tube-bridge --http # Streamable HTTP on port 8080
docker run --rm -p 8080:8080 ghcr.io/thewhitewater/tube-bridge:latest
The health endpoint is http://localhost:8080/health; the Streamable HTTP endpoint is http://localhost:8080/mcp.
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.
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 --http
Then 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.
| Variable | Required | Purpose |
|---|---|---|
YOUTUBE_API_KEY | No | Enables the 3 API-only tools and upgrades supported discovery calls |
TUBE_BRIDGE_PROXY | No | Routes yt-dlp and transcript requests through an HTTP(S) or SOCKS proxy |
TUBE_BRIDGE_CACHE | No | Changes the directory containing cache.db and corpus.db |
TUBE_BRIDGE_AUTH_KEY | No | Protects self-hosted HTTP MCP routes with a static Bearer token |
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 fastembed
/mcp for self-hosted remote use;code, source, and retryable fields;GitHub Releases include tube-bridge-agent-plugin-<version>.zip, containing:
tube-bridge-research skill;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.
If YouTube blocks requests from your network, set TUBE_BRIDGE_PROXY. Keep proxy credentials in environment variables rather than committed configuration.
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 -q
python 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.
MIT — see LICENSE.
FAQs
Tube Bridge — YouTube MCP server for AI agents. 17 tools: search, transcripts, frames, semantic corpus, comments. Zero keys + optional API v3.
We found that tube-bridge demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
NIST disclosed an unreleased AI tool called V-etalon and opened a broad inquiry into NVD modernization after years of automation plans produced no public enrichment system.
Security News
In his AI Council 2026 talk, Feross Aboukhadijeh covers recent package compromises, vulnerability discovery, and a more automated security model.
Security News
A new federal program will let vetted U.S. cybersecurity firms help investigate and disrupt foreign cybercrime groups under government direction.