tube-bridge

YouTube MCP server for AI agents — search, discovery, transcripts, comments, semantic corpus.

16 tools. 13 without API key. 3 with optional YouTube Data API v3 key.

Quick Start

# 1. Install the published package
pip install tube-bridge

# 2. Run (no API key needed for 13 of 16 tools)
tube-bridge                    # stdio mode (local MCP clients)
tube-bridge --http             # HTTP mode (remote, port 8080)

# 3. Or run the published container
docker run --rm -p 8080:8080 ghcr.io/thewhitewater/tube-bridge:latest

# MCP endpoints: stdio via `tube-bridge`, HTTP at http://localhost:8080/mcp

16 tools: 13 callable without any setup. 3 unlock with a Data API v3 key. 5 corpus tools use local embeddings.

Tools (16)

Tool	API Key	Description
youtube_search	❌→✅	Search videos. Data API v3 primary when key set, yt-dlp fallback. Rich filters: date, channel, duration, order
youtube_get_video_info	❌→✅	Full metadata: title, views, channel, tags, description. Dual-source, cached
youtube_get_trending	❌→✅	Trending videos. API v3 primary, yt-dlp fallback
youtube_get_channel_videos	❌	Recent uploads from any channel (@handle or URL)
youtube_get_playlist	❌	All videos in a playlist
youtube_get_transcript	❌	Transcript/subtitles. Plain text or [MM:SS] timestamps. Manual > ASR
youtube_get_available_languages	❌	Subtitle languages with manual/auto-generated flags
youtube_get_comments	✅	Top-level comments with likes and reply counts
youtube_search_channels	✅	Channel search with subscriber counts and filters
youtube_get_channel_info	✅	Detailed channel stats: subscribers, views, country, keywords
tube_bridge_help	❌	Server documentation accessible via MCP
corpus_create	❌	Create a named corpus for semantic transcript search
corpus_add	❌	Add video transcript to a corpus. Auto-fetches (network), chunks, embeds locally
corpus_search	❌	Semantic search within a corpus. Returns chunks with scores, timestamps, video IDs
corpus_list	❌	List all corpora with chunk and video counts
corpus_delete	❌	Delete a corpus and all its chunks/vectors permanently

Key: ❌ = no key needed; ✅ = key required; ❌→✅ = works without key, upgrades with key.

Transport Endpoints

• /mcp — Streamable HTTP (recommended for remote deployments)
• /sse — SSE (legacy; deprecated)
• /health — Health check (always open)
• stdio — Direct child process for local MCP clients

Optional Auth

Set TUBE_BRIDGE_AUTH_KEY to enable Bearer-token protection on all remote routes except /health (/mcp, /sse, /messages). The /health endpoint remains open. If not set, open access (for local dev).

MCP client config with auth:

{
  "mcpServers": {
    "tube-bridge": {
      "type": "http",
      "url": "https://your-app.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-key"
      }
    }
  }
}

YouTube Data API v3 (Optional)

For comments, channel search, channel info, and higher-quality search results, obtain your own YouTube Data API key from Google Cloud Console and set it as an environment variable:

export YOUTUBE_API_KEY="your-key-here"

3 tools unlock with a key. Search and video_info also upgrade to higher-quality Data API v3 results. With the key present, yt-dlp is used as a fallback when quota is exhausted.

Bridge Corpus — Semantic Search

Semantic search over YouTube transcripts using local embeddings. Useful for research workflows — build a corpus of videos on a topic and search across them.

corpus_create("ai-agents", "AI Agents Research")     # Named corpus
corpus_add("ai-agents", "dQw4w9WgXcQ")               # Auto-chunks + embeds (transcript fetched over network)
corpus_search("ai-agents", "memory systems")          # Semantic search with scores
corpus_list()                                          # List all corpora
corpus_delete("ai-agents")                             # Delete permanently

• Chunking: by transcript segments, 80-second windows with 20-second overlap
• Embeddings: fastembed (BGE-small-en-v1.5, 384-dim); local inference after model assets are available; initial model acquisition may require network; no embedding API setup
• Storage: corpus.db — separate SQLite file from cache.db, same directory (~/.tube_bridge)

Architecture

tube_bridge/
├── server.py          # MCP wiring: tool registration + dispatch
├── tools.py           # All tool implementations (async, cached, retry)
├── cli.py             # Runtime selection: stdio or HTTP
├── transport.py       # Streamable HTTP + SSE ASGI routes, auth, identity, health
├── cache.py           # Persistent SQLite cache (cache.db) for transcripts + video metadata
├── corpus.py          # Semantic search (corpus.db, sqlite-vec + fastembed)
└── youtube/
    ├── client.py      # yt-dlp subprocess client (retry + backoff + proxy)
    ├── api.py         # YouTube Data API v3 client (stdlib urllib, no third-party Google SDK)
    ├── transcript.py  # youtube-transcript-api wrapper (manual > ASR, proxy)
    └── models.py      # VideoInfo dataclass

• Dual-source: Data API v3 primary → yt-dlp fallback for search, video_info, trending
• Cache: SQLite cache.db (persistent, survives restarts) + lru_cache hot layer
• Corpus: SQLite corpus.db (separate database) with sqlite-vec vectors
• Data API client: Python stdlib urllib only; no google-api-python-client dependency
• Retry: 2 retries with exponential backoff for yt-dlp subprocess
• Proxy: TUBE_BRIDGE_PROXY env var routes both yt-dlp and transcript API through a proxy
• Graceful: quota exceeded → falls through to yt-dlp; stderr captured in _warning field

Self-Hosting

tube-bridge is an MIT self-hosted individual MCP — never a SaaS or managed transcript-hosting product. The Railway deployment below is solely a disposable try-before-install demo.

Railway (Disposable Demo)

git clone https://github.com/TheWhiteWater/tube-bridge
cd tube-bridge
railway init --name tube-bridge
railway up --service tube-bridge --detach

# Set in Railway dashboard → Variables:
#   YOUTUBE_API_KEY  (uses isolated demo GCP project, separate from Operator keys)
#   TUBE_BRIDGE_PROXY (recommended for transcripts from datacenter IPs)
#   TUBE_BRIDGE_AUTH_KEY (optional, protects all remote routes except /health)
#   TUBE_BRIDGE_DEMO_MODE=1
#   TUBE_BRIDGE_TRUST_PROXY_HEADERS=1
#   TUBE_BRIDGE_CLIENT_IP_HEADER=x-real-ip

Active demo controls: exactly 5 attempted Data API v3 operations per observed client IP for the current process lifetime; the sixth receives a structured rejection. Keyless operations do not consume the allowance. Railway's overwritten X-Real-IP is the trusted identity source; client-supplied X-Forwarded-For is not trusted on the production demo. Counters are salted/HMAC-keyed and memory-only, with no time reset; a process restart resets them.

Demo data handling: the application does not write raw client IPs to its SQLite files or application access logs, and /health exposes aggregate counters only. There are no accounts, persistent volumes, or backups. Corpus content and vectors are stored only on ephemeral deployment storage. Frozen clocks prove transactional deletion at the persisted 600-second deadline; non-invasive live sampling first observed complete absence 1.577 seconds after that deadline. Self-hosted mode is unchanged and persistent by default.

Docker

docker build -t tube-bridge .
docker run -p 8080:8080 -e YOUTUBE_API_KEY=... tube-bridge

Any Host

pip install mcp==1.28.1 yt-dlp youtube-transcript-api starlette uvicorn sqlite-vec fastembed
python3 server.py --http --port 8080 --host 0.0.0.0

MCP Client Config

stdio (local):

{
  "mcpServers": {
    "tube-bridge": {
      "command": "python3",
      "args": ["/path/to/tube-bridge/server.py"]
    }
  }
}

Streamable HTTP (recommended for remote):

{
  "mcpServers": {
    "tube-bridge": {
      "type": "http",
      "url": "https://your-app.example.com/mcp"
    }
  }
}

SSE (legacy):

{
  "mcpServers": {
    "tube-bridge": {
      "type": "sse",
      "url": "https://your-app.example.com/sse"
    }
  }
}

Product Boundary

Current State

• MIT self-hosted library — 16 MCP tools, all transports, cache/corpus logic. Available on GitHub.
• Disposable Railway demo — tube-bridge-production.up.railway.app is a controlled try-before-install demo only. Not a SaaS or managed product.
• Disposable-demo P0 controls are active and accepted. The production deployment enforces the 5-operation process-lifetime allowance from Railway-overwritten X-Real-IP, uses privacy-preserving memory-only counters, has no volume/backups/accounts, and uses a persisted 600-second corpus deadline with deterministic deadline deletion and live absence observed at the first +1.577-second sample.
• Published self-hosted core. GitHub Release, PyPI package, and public GHCR image are live. Frozen 125-test core acceptance, clean install, installed CLI/MCP, Docker handshake, wheel+sdist, twine, and hosted CI checks pass.

Full Publication Scope

The self-hosted core is fully published through GitHub Release, PyPI, and GHCR. The separately gated disposable Railway demo now has accepted quota, privacy, restart-reset, and corpus-retention controls. Neither surface carries an SLA or managed-hosting promise. Conditional quota-extension and proxy-reliability work is reviewed before broad announcement and at its documented usage/availability triggers; Railway persistence/backups is N/A while the demo remains no-volume and non-durable.

What tube-bridge Is NOT

• Not a SaaS or managed transcript-hosting product.
• No commercial extension, product gateway, billing, entitlement, or managed higher-quota tier.
• Grabbit MCP is a completely separate companion MCP (live endpoint). There is no connector, dependency, shared service, bundled workflow, or code integration: an agent may use tube-bridge to find videos and independently use Grabbit to save links.
• Browser extension is outside this project's release gate and must not be architected here.

Decision Sources

• PROJECT_VISION.md — product boundaries, tool baseline, open-core scope.
• docs/planning/PUBLICATION_READINESS.md — readiness checklist (P0/P1/P2 items, no-go gates).
• docs/adr/001-demo-api-quota-and-product-boundary.md — architecture direction for demo isolation, fixed 5-operation limit, 10-minute corpus TTL, self-hosted boundary, and full-publication scope.

Testing

python3 test_tools.py

This remains an optional live smoke against YouTube. Formal acceptance uses python3 -m pytest tests -q; the current frozen suite contains 209 deterministic tests. Hosted GitHub Actions CI passes on Python 3.12 and 3.13.

Known Limitations

• Datacenter IPs (Railway, AWS, etc.): YouTube may block anonymous requests from cloud IP ranges. youtube_search and youtube_get_video_info are unaffected with a Data API v3 key. youtube_get_transcript may fail with bot detection — set TUBE_BRIDGE_PROXY to a residential proxy to work around this.
• Disposable demo retention: demo corpora are deliberately non-durable. The worker is scheduled for the persisted 10-minute deadline (deterministic tests), and live sampling first observed absence 1.577 seconds later; a restart may remove data sooner because Railway has no attached volume. Self-hosted instances retain corpora under ~/.tube_bridge.
• yt-dlp anonymous search: degraded by YouTube in recent months. Prefer Data API v3 when available.

License

MIT — see LICENSE file.