tube-bridge

Normally your MCP client launches that command for you. Choose your client below.

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.

- Storage:SQLite plus sqlite-vec in~/.tube_bridge/corpus.db
- Embeddings: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

SetTUBE_BRIDGE_CACHEto 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_framerequiresffmpegonPATH; the Docker image already includes it.

Each call downloads a short temporary section aroundtimestamp_ms, returns one bounded JPEG as MCPImageContent, 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 ishttp://localhost:8080/health; the Streamable HTTP endpoint ishttp://localhost:8080/mcp.

Registry-aware clients can install the PyPI distribution withuvxand launch the stdio server without a hosted intermediary.

{ "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

{ "mcpServers": { "tube-bridge": { "type": "http", "url": "https://your-host.example/mcp", "headers": { "Authorization": "Bearer <your-key>" } } } }

/healthremains public./mcp,/sse, and/messagesrequire the Bearer key whenTUBE_BRIDGE_AUTH_KEYis set. Legacy SSE is available at/ssefor clients that still need it.

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

- stdio 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 stablecode,source, andretryablefields;
- cache and corpus databases are separate and remain operator-owned.

- the local stdio MCP configuration;
- thetube-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.

- 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, setTUBE_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.pyis an optional live YouTube smoke test. The deterministic test suite does not call YouTube.

Search global news using natural language. Webz.io News Search API returns the most relevant articles and content, with filters for source, country, language, date, sentiment, and category.

BYOK Reddit/YouTube research CLI with a tamper-evident audit log and an MCP server.

An agent-based tool for web search and advanced research, including analysis of PDFs, documents, images, and YouTube transcripts.

An MCP server providing search capabilities for Reddit, YouTube, and Twitter.

Provides search capabilities and data retrieval from SerpAPI and YouTube for AI assistants.

Get YouTube transcripts, search videos, browse channels, and extract playlists from any AI agent — powered by TranscriptAPI.com with no API key required.

Search a YouTube video's transcript and read its frames — every answer cites a clickable timestamp.

Search YouTube videos and retrieve their transcripts using the YouTube API.

A set of tools to interact with YouTube, including video search, transcript extraction, and comment retrieval.

Connect AI assistants to YouTube - search, transcripts, metadata, and more.