{
  "markdown": "# tube-bridge\n\n<!-- mcp-name: io.github.TheWhiteWater/tube-bridge -->\n\n**Self-hosted YouTube research for AI agents.**\n\nSearch videos and channels, read transcripts and comments, extract timestamped frames, and build private semantic-search corpora — through 17 MCP tools.\n\n[![CI](https://github.com/TheWhiteWater/tube-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/TheWhiteWater/tube-bridge/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/tube-bridge.svg)](https://pypi.org/project/tube-bridge/)\n[![PyPI downloads](https://img.shields.io/pypi/dw/tube-bridge.svg)](https://pypistats.org/packages/tube-bridge)\n[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://python.org)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Glama](https://glama.ai/mcp/servers/TheWhiteWater/tube-bridge/badges/score.svg)](https://glama.ai/mcp/servers/TheWhiteWater/tube-bridge)\n\n- **14 of 17 tools need no YouTube API key.**\n- **Local-first corpus:** transcripts, vectors, and indexes stay on your machine.\n- **Useful research output:** titles, similarity scores, canonical video URLs, and timestamp links.\n- **One tool for one frame:** return visual evidence near a transcript finding without keeping media files.\n- **Self-hosted and MIT:** no account, hosted intermediary, managed storage, or vendor lock-in.\n\nThanks 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.\n\n## Connect in a minute\n\nThe simplest setup uses [`uvx`](https://docs.astral.sh/uv/guides/tools/), which runs the published PyPI package in an isolated environment:\n\n```bash\nuvx tube-bridge\n```\n\nNormally your MCP client launches that command for you. Choose your client below.\n\n> [!NOTE]\n> 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.\n\n### Claude Desktop\n\nOpen **Settings → Developer → Edit Config** and add:\n\n```json\n{\n  \"mcpServers\": {\n    \"tube-bridge\": {\n      \"command\": \"uvx\",\n      \"args\": [\"tube-bridge\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop after saving the configuration.\n\n### Claude Code\n\n```bash\nclaude mcp add --scope user tube-bridge -- uvx tube-bridge\n```\n\n### Cursor\n\nCreate `.cursor/mcp.json` in your project, or add the server to your user-level MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"tube-bridge\": {\n      \"command\": \"uvx\",\n      \"args\": [\"tube-bridge\"]\n    }\n  }\n}\n```\n\n### VS Code\n\nCreate `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"tube-bridge\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"tube-bridge\"]\n    }\n  }\n}\n```\n\n### Codex CLI\n\n```bash\ncodex mcp add tube-bridge -- uvx tube-bridge\n```\n\n## Pi package\n\nPi can load the package-relative adapter and the canonical `tube-bridge-research` skill from the same Git source:\n\n```bash\npython3 -m pip install tube-bridge==1.1.6\npi install git:github.com/TheWhiteWater/tube-bridge@v1.1.6\npi list\n```\n\nThis 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.\n\nThe 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`.\n\nRemove the package with:\n\n```bash\npi remove git:github.com/TheWhiteWater/tube-bridge@v1.1.6\n```\n\nIf 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.\n\n## Try the complete research workflow\n\nAsk your agent:\n\n> 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.\n\nThe agent can complete that request with this tool sequence:\n\n```text\nyoutube_search(query=\"local-first AI agents\", order=\"date\")\nyoutube_get_transcript(url=\"https://www.youtube.com/watch?v=VIDEO_ID\", with_timestamps=true)\ncorpus_create(corpus_id=\"local-agents\", label=\"Local-first AI Agents\")\ncorpus_add(corpus_id=\"local-agents\", url=\"https://www.youtube.com/watch?v=VIDEO_ID\")\ncorpus_search(corpus_id=\"local-agents\", query=\"memory architecture\")\nyoutube_get_frame(url=\"https://www.youtube.com/watch?v=VIDEO_ID\", timestamp_ms=FOUND_TIME_MS)\n```\n\nAdd more videos with `corpus_add`, then use `corpus_search` to search across all of their transcripts at once.\n\n## Tools\n\n| Tool | YouTube API key | What it does |\n|---|:---:|---|\n| `youtube_search` | Optional | Search videos with date, channel, duration, and ordering filters |\n| `youtube_get_video_info` | Optional | Get title, duration, views, channel, description, and tags |\n| `youtube_get_trending` | Optional | Get currently trending videos |\n| `youtube_get_channel_videos` | No | Get recent uploads from a channel URL or `@handle` |\n| `youtube_get_playlist` | No | Get videos from a playlist |\n| `youtube_get_transcript` | No | Get a transcript, optionally with `[MM:SS]` timestamps |\n| `youtube_get_frame` | No | Return one ephemeral JPEG near an integer-millisecond timestamp |\n| `youtube_get_available_languages` | No | List manual and auto-generated subtitle tracks |\n| `youtube_get_comments` | Required | Get top-level comments with likes and reply counts |\n| `youtube_search_channels` | Required | Search channels and filter by subscriber count |\n| `youtube_get_channel_info` | Required | Get channel statistics, country, and keywords |\n| `corpus_create` | No | Create a named local corpus |\n| `corpus_add` | No | Fetch, chunk, and locally embed a video transcript |\n| `corpus_search` | No | Semantically search a corpus with timestamped results |\n| `corpus_list` | No | List corpora with video and chunk counts |\n| `corpus_delete` | No | Permanently delete a corpus and its vectors |\n| `tube_bridge_help` | No | Read runtime documentation and known limitations |\n\n**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.\n\n## Optional YouTube Data API key\n\nA YouTube Data API v3 key unlocks comments, channel search, and channel details. It also improves search, video information, and trending reliability.\n\nCreate a key in [Google Cloud Console](https://console.cloud.google.com/), enable **YouTube Data API v3**, and expose it to the process launching tube-bridge:\n\n```bash\nexport YOUTUBE_API_KEY=\"your-key\"\n```\n\nKeep keys out of committed MCP configuration files. Use your client's secret/environment support where available.\n\n## Local semantic corpus\n\nCorpus storage and embedding inference are local to the machine running tube-bridge.\n\n- **Storage:** SQLite plus sqlite-vec in `~/.tube_bridge/corpus.db`\n- **Embeddings:** BGE-small-en-v1.5 through fastembed\n- **Chunking:** 80-second windows with 20-second overlap\n- **Ranking:** overlap deduplication and source-aware per-video limits\n- **Results:** similarity score, time span, video title, canonical URL, and timestamp URL\n\nSet `TUBE_BRIDGE_CACHE` to move both corpus and cache databases:\n\n```bash\nexport TUBE_BRIDGE_CACHE=\"/path/to/tube-bridge-data\"\n```\n\nThe embedding model may be downloaded on first use. After the assets are available, embedding inference does not require an external model API.\n\n## Frame extraction\n\n`youtube_get_frame` requires `ffmpeg` on `PATH`; the Docker image already includes it.\n\nEach 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.\n\n## Other ways to run\n\n### Persistent PyPI installation\n\n```bash\npip install tube-bridge\n\ntube-bridge          # stdio\ntube-bridge --http   # Streamable HTTP on port 8080\n```\n\n### Docker\n\n```bash\ndocker run --rm -p 8080:8080 ghcr.io/thewhitewater/tube-bridge:latest\n```\n\nThe health endpoint is `http://localhost:8080/health`; the Streamable HTTP endpoint is `http://localhost:8080/mcp`.\n\n### Official MCP Registry\n\nRegistry name: [`io.github.TheWhiteWater/tube-bridge`](https://registry.modelcontextprotocol.io/)\n\nRegistry-aware clients can install the PyPI distribution with `uvx` and launch the stdio server without a hosted intermediary.\n\n## Remote HTTP configuration\n\nFor an HTTP instance you operate:\n\n```json\n{\n  \"mcpServers\": {\n    \"tube-bridge\": {\n      \"type\": \"http\",\n      \"url\": \"https://your-host.example/mcp\"\n    }\n  }\n}\n```\n\nProtect remote MCP routes by setting a server-side Bearer key:\n\n```bash\nexport TUBE_BRIDGE_AUTH_KEY=\"choose-a-long-random-value\"\ntube-bridge --http\n```\n\nThen configure a header-capable client:\n\n```json\n{\n  \"mcpServers\": {\n    \"tube-bridge\": {\n      \"type\": \"http\",\n      \"url\": \"https://your-host.example/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer <your-key>\"\n      }\n    }\n  }\n}\n```\n\n`/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.\n\n## Environment variables\n\n| Variable | Required | Purpose |\n|---|:---:|---|\n| `YOUTUBE_API_KEY` | No | Enables the 3 API-only tools and upgrades supported discovery calls |\n| `TUBE_BRIDGE_PROXY` | No | Routes yt-dlp and transcript requests through an HTTP(S) or SOCKS proxy |\n| `TUBE_BRIDGE_CACHE` | No | Changes the directory containing `cache.db` and `corpus.db` |\n| `TUBE_BRIDGE_AUTH_KEY` | No | Protects self-hosted HTTP MCP routes with a static Bearer token |\n\n## How it works\n\n```text\nMCP client\n   │\n   ├── discovery and metadata ── Data API v3 (when configured)\n   │                          └─ yt-dlp fallback\n   ├── transcripts ───────────── youtube-transcript-api\n   ├── timestamped frames ────── yt-dlp + ffmpeg → ephemeral JPEG\n   └── semantic corpus ───────── SQLite + sqlite-vec + local fastembed\n```\n\n- stdio is recommended for local clients;\n- Streamable HTTP is available at `/mcp` for self-hosted remote use;\n- successful fallback responses keep their normal schemas;\n- controlled failures use typed MCP errors with stable `code`, `source`, and `retryable` fields;\n- cache and corpus databases are separate and remain operator-owned.\n\n## Agent Plugin preview\n\n[GitHub Releases](https://github.com/TheWhiteWater/tube-bridge/releases) include `tube-bridge-agent-plugin-<version>.zip`, containing:\n\n- the local stdio MCP configuration;\n- the `tube-bridge-research` skill;\n- research templates and source-evaluation guidance.\n\nAgent 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.\n\n## Known limitations\n\n- YouTube can restrict anonymous yt-dlp and transcript requests, especially from cloud-hosting IP ranges.\n- A Data API key improves discovery and metadata reliability but does not replace transcript access.\n- Initial local embedding-model setup may require network access and additional disk space.\n- tube-bridge is self-hosted software; it does not provide accounts, public hosted access, managed storage, or an SLA.\n\nIf YouTube blocks requests from your network, set `TUBE_BRIDGE_PROXY`. Keep proxy credentials in environment variables rather than committed configuration.\n\n## Development\n\n```bash\ngit clone https://github.com/TheWhiteWater/tube-bridge.git\ncd tube-bridge\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -r requirements-release.txt\npip install --no-deps -e .\npip install pytest pytest-asyncio pytest-mock build twine\npython -m pytest tests -q\n```\n\n`python test_tools.py` is an optional live YouTube smoke test. The deterministic test suite does not call YouTube.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) to contribute. Security reports should follow [SECURITY.md](SECURITY.md).\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 12637,
  "sha": "b1f308636984338c6922f20955007424d67a80adbc8a0089787f778f3ad9f0a3",
  "repo_slug": "thewhitewater/tube-bridge",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_thewhitewater_tube_bridge_bef5a626/readme"
}