Skip to main content
Glama

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

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

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

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.

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          # stdio
tube-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

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

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

License

MIT — see LICENSE.

Available Tools

17 tools
corpus_addA
Destructive

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_createA
Idempotent

Create a named corpus for semantic search over transcripts. Each corpus uses a fixed embedding model.

Inputs: corpus_id (required), label.

corpus_deleteA
DestructiveIdempotent

Delete a corpus and all its chunks/vectors permanently.

Inputs: corpus_id (required).

corpus_listA
Read-onlyIdempotent

List all available corpora with chunk and video counts.

Inputs: no named parameters.

tube_bridge_helpA
Read-onlyIdempotent

Get tube-bridge documentation: available tools, architecture, known limitations, API key setup.

Inputs: no named parameters.

youtube_get_available_languagesA
Read-onlyIdempotent

Available subtitle languages for a video. Shows manual vs auto-generated.

Inputs: url (required).

youtube_get_channel_infoA
Read-onlyIdempotent

Detailed channel metadata: subscribers, views, videos, country, keywords. Requires YOUTUBE_API_KEY.

Inputs: channel_id (required).

youtube_get_channel_videosA
Read-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_commentsA
Read-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_frameA
Read-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_playlistA
Read-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_transcriptA
Read-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_video_infoA
Read-onlyIdempotent

Detailed metadata for a YouTube video: title, duration, views, channel, description, tags.

Inputs: url (required).

youtube_search_channelsA
Read-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

    A4.1/5.0

    Scored across 17 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness5/5

    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

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that provides AI assistants with powerful tools to interact with YouTube, including video searching, transcript extraction, comment retrieval, and more.
      8
      19
      Apache 2.0
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      An 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
      -