tube-bridge

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.

[CI] [PyPI] [PyPI downloads] [Python] [License] [Glama]

• 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-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. 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-bridge

Cursor

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-bridge

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.7pi install git:github.com/TheWhiteWater/[email protected]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/[email protected]

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.

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

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.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

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          # stdiotube-bridge --http   # Streamable HTTP on port 8080

Docker

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.

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 --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.

Environment variables

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 fastembed

• stdio is recommended for local clients;
• Streamable HTTP is available at /mcp for self-hosted remote use;
• successful fallback responses keep their normal schemas;
• controlled failures use typed MCP errors with stable code, source, and retryable fields;
• 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-research skill;
• 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.gitcd tube-bridgepython3 -m venv .venvsource .venv/bin/activatepip install -r requirements-release.txtpip install --no-deps -e .pip install pytest pytest-asyncio pytest-mock build twinepython -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.

License

MIT — see LICENSE.