tube-bridge

tube-bridge

面向 AI Agent 的可自托管 YouTube 研究工具。

搜索视频和频道，阅读字幕和评论，提取带时间戳的帧，并构建私有语义搜索语料库——通过 17 个 MCP 工具实现。

• 17 个工具中有 14 个无需 YouTube API 密钥。
• **本地优先语料库：**字幕、向量和索引都保留在你的设备上。
• **实用的研究结果：**标题、相似度分数、规范视频 URL 和时间戳链接。
• **一帧只需一个工具：**无需保留媒体文件，即可返回字幕检索结果附近的视觉证据。
• **可自托管，采用 MIT 许可证：**无需账户、托管中介或托管存储，也不会被供应商锁定。

感谢所有已经在使用 tube-bridge 的人。如果它为你节省了时间，不妨为仓库点个星标——这有助于其他人发现本项目，也能让我们知道继续发布此类作品是值得的。

一分钟内完成连接

最简单的设置方式是使用 uvx，它会在隔离环境中运行已发布到 PyPI 的软件包：

uvx tube-bridge

通常，MCP 客户端会为你启动此命令。请在下方选择你的客户端。

说明

tube-bridge 需要 Python 3.12 或更高版本。API 密钥为可选项。ffmpeg 仅在使用 youtube_get_frame 时需要；首次执行嵌入操作时，可能会下载本地模型。

Claude Desktop

打开 设置 → 开发者 → 编辑配置 并添加：

{
  "mcpServers": {
    "tube-bridge": {
      "command": "uvx",
      "args": ["tube-bridge"]
    }
  }
}

保存配置后，重启 Claude Desktop。

Claude Code

claude mcp add --scope user tube-bridge -- uvx tube-bridge

Cursor

在项目中创建 .cursor/mcp.json，或将服务添加到用户级 MCP 配置中：

{
  "mcpServers": {
    "tube-bridge": {
      "command": "uvx",
      "args": ["tube-bridge"]
    }
  }
}

VS Code

创建 .vscode/mcp.json：

{
  "servers": {
    "tube-bridge": {
      "type": "stdio",
      "command": "uvx",
      "args": ["tube-bridge"]
    }
  }
}

Codex CLI

codex mcp add tube-bridge -- uvx tube-bridge

Pi 软件包

Pi 可以从同一 Git 源加载相对于软件包的适配器和规范的 tube-bridge-research 技能：

python3 -m pip install tube-bridge==1.1.6
pi install git:github.com/TheWhiteWater/[email protected]
pi list

这会注册一个状态工具，以及带有 tube_bridge_ 前缀的全部 17 个 MCP 工具。适配器会读取现有的 plugin.json 和 mcp.json，只启动本地 stdio 运行时，保留有长度限制的文本和图像内容，并且仅转发允许列表中的子进程环境变量。

Pi 软件包管理器会安装 Node 适配器依赖项，但不会安装 Python 或 ffmpeg。请确保 Pi 使用的 python3 为 Python 3.12+，且已安装 tube-bridge 依赖项；如需使用 youtube_get_frame，请单独安装 ffmpeg。默认情况下，Pi 管理的状态存储在平台数据目录下；设置 TUBE_BRIDGE_PI_DATA 可更改该根目录。显式设置的 TUBE_BRIDGE_CACHE 仍优先用于运行时数据库。可选的实时帧检查命令为 /tube-bridge-selftest frame。

使用以下命令移除软件包：

pi remove git:github.com/TheWhiteWater/[email protected]

如果桌面客户端找不到 uvx，请将 "uvx" 替换为其绝对路径；在 macOS/Linux 上运行 which uvx，在 Windows 上运行 where.exe uvx 即可查到该路径。

试用完整研究工作流

向你的 Agent 提问：

在 YouTube 上搜索近期有关本地优先 AI Agent 的视频。阅读最相关结果的字幕，将其添加到名为 local-agents 的语料库中，查找讨论记忆的片段，返回带时间戳的来源链接，并提取该时刻的一帧。

Agent 可以通过以下工具调用顺序完成该请求：

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)

使用 corpus_add 添加更多视频，然后使用 corpus_search 一次性搜索所有视频的字幕。

工具

工具	YouTube API 密钥	功能
youtube_search	可选	按日期、频道、时长和排序筛选条件搜索视频
youtube_get_video_info	可选	获取标题、时长、观看次数、频道、说明和标签
youtube_get_trending	可选	获取当前热门视频
youtube_get_channel_videos	否	获取频道 URL 或 @handle 的近期上传视频
youtube_get_playlist	否	获取播放列表中的视频
youtube_get_transcript	否	获取字幕稿，可选择添加 [MM:SS] 时间戳
youtube_get_frame	否	返回接近整数毫秒时间戳的一张临时 JPEG 图片
youtube_get_available_languages	否	列出人工字幕和自动生成的字幕轨道
youtube_get_comments	必需	获取顶级评论及其点赞数和回复数
youtube_search_channels	必需	搜索频道并按订阅者数量筛选
youtube_get_channel_info	必需	获取频道统计数据、国家/地区和关键词
corpus_create	否	创建命名的本地语料库
corpus_add	否	获取视频字幕稿、分块并在本地生成嵌入
corpus_search	否	语义搜索语料库并返回带时间戳的结果
corpus_list	否	列出语料库及其视频和分块数量
corpus_delete	否	永久删除语料库及其向量
tube_bridge_help	否	查看运行时文档和已知限制

否表示不需要 YouTube Data API 密钥；但可能仍需连接网络以访问 YouTube。搜索、视频信息和热门视频功能无需密钥即可通过 yt-dlp 使用；配置密钥后，这些功能会升级为使用 Data API v3。

可选的 YouTube Data API 密钥

YouTube Data API v3 密钥可启用评论、频道搜索和频道详情功能。它还能提高搜索、视频信息和热门视频功能的可靠性。

在 Google Cloud Console 中创建密钥，启用 YouTube Data API v3，并将密钥提供给启动 tube-bridge 的进程：

export YOUTUBE_API_KEY="your-key"

不要将密钥写入已提交的 MCP 配置文件。在可用时，请使用客户端的密钥或环境变量支持。

本地语义语料库

语料库存储和嵌入推理均在运行 tube-bridge 的机器上本地完成。

• 存储： SQLite 和 sqlite-vec，位于 ~/.tube_bridge/corpus.db
• 嵌入： 通过 fastembed 使用 BGE-small-en-v1.5
• 分块： 80 秒窗口，重叠 20 秒
• 排序： 重叠内容去重，并按视频来源限制结果数量
• 结果： 相似度分数、时间范围、视频标题、规范 URL 和时间戳 URL

设置 TUBE_BRIDGE_CACHE 可同时更改语料库和缓存数据库的位置：

export TUBE_BRIDGE_CACHE="/path/to/tube-bridge-data"

嵌入模型可能会在首次使用时下载。资源可用后，嵌入推理无需调用外部模型 API。

帧提取

youtube_get_frame 需要在 PATH 中提供 ffmpeg；Docker 镜像已包含该程序。

每次调用都会下载 timestamp_ms 附近的一小段临时媒体，返回一张大小受限的 JPEG，作为 MCP ImageContent，并在返回前删除临时媒体。该功能不会创建帧或剪辑库。

其他运行方式

持久化 PyPI 安装

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

健康检查端点为 http://localhost:8080/health；Streamable HTTP 端点为 http://localhost:8080/mcp。

官方 MCP Registry

注册表名称：io.github.TheWhiteWater/tube-bridge

支持注册表的客户端可以通过 uvx 安装 PyPI 发行包，并启动 stdio 服务，无需托管中间服务。

远程 HTTP 配置

对于你运行的 HTTP 实例：

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

设置服务端 Bearer 密钥以保护远程 MCP 路由：

export TUBE_BRIDGE_AUTH_KEY="choose-a-long-random-value"
tube-bridge --http

然后配置支持请求头的客户端：

{
  "mcpServers": {
    "tube-bridge": {
      "type": "http",
      "url": "https://your-host.example/mcp",
      "headers": {
        "Authorization": "Bearer <your-key>"
      }
    }
  }
}

/health 仍然公开可访问。设置 TUBE_BRIDGE_AUTH_KEY 后，访问 /mcp、/sse 和 /messages 需要 Bearer 密钥。对于仍需要使用旧版 SSE 的客户端，可通过 /sse 访问。

环境变量

变量	必需	用途
YOUTUBE_API_KEY	否	启用 3 个仅限 API 的工具，并提升受支持的发现调用能力
TUBE_BRIDGE_PROXY	否	通过 HTTP(S) 或 SOCKS 代理转发 yt-dlp 和字幕请求
TUBE_BRIDGE_CACHE	否	更改包含 cache.db 和 corpus.db 的目录
TUBE_BRIDGE_AUTH_KEY	否	使用静态 Bearer 令牌保护自托管 HTTP MCP 路由

工作原理

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；
• 自托管远程场景可通过 /mcp 使用 Streamable HTTP；
• 成功的回退响应会保留其常规架构；
• 可控故障会使用带有稳定 code、source 和 retryable 字段的类型化 MCP 错误；
• 缓存数据库和语料库数据库彼此独立，并由运营方持有。

Agent 插件预览

GitHub Releases 包含 tube-bridge-agent-plugin-<version>.zip，其中包括：

• 本地 stdio MCP 配置；
• tube-bridge-research 技能；
• 研究模板和来源评估指南。

Agent Plugins v1 未标准化依赖项安装方式。请在插件宿主所用的环境中安装 Python 3.12+、ffmpeg 和软件包依赖项。此捆绑包不包含凭据。

已知限制

• YouTube 可能会限制匿名 yt-dlp 和字幕请求，尤其是来自云托管 IP 地址段的请求。
• Data API 密钥可提高发现能力和元数据的可靠性，但不能替代字幕访问。
• 初次设置本地嵌入模型可能需要网络访问和额外磁盘空间。
• tube-bridge 是可自托管软件；它不提供账户、公开托管访问、托管存储或 SLA。

如果 YouTube 屏蔽了来自你所在网络的请求，请设置 TUBE_BRIDGE_PROXY。请将代理凭据保存在环境变量中，而不是提交到配置文件中。

开发

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 是可选的 YouTube 实时冒烟测试。确定性测试套件不会调用 YouTube。

请参阅 CONTRIBUTING.md 了解如何贡献。安全问题报告请遵循 SECURITY.md。

许可证

MIT — 详见 LICENSE。