TheWhiteWater/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.
- **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:
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:
Restart Claude Desktop after saving the configuration.
Claude Code
Cursor
Create .cursor/mcp.json in your project, or add the server to your user-level MCP configuration:
VS Code
Create .vscode/mcp.json:
Codex CLI
Pi package
Pi can load the package-relative adapter and the canonical tube-bridge-research skill from the same Git source:
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:
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:
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 |