tube-bridge

tube-bridge

AI エージェント向けのセルフホスト型 YouTube リサーチ。

動画やチャンネルを検索し、文字起こしとコメントを読み、タイムスタンプ付きのフレームを抽出し、非公開のセマンティック検索コーパスを構築できます。17 個の MCP ツールを利用します。

• 17 個のツールのうち 14 個は YouTube API キー不要です。
• **ローカル優先のコーパス：**文字起こし、ベクトル、インデックスはマシン上に保存されます。
• **リサーチに役立つ出力：**タイトル、類似度スコア、正規の動画 URL、タイムスタンプ付きリンク。
• **1 フレーム取得用のツール：**メディアファイルを保持せずに、文字起こしから見つかった箇所の近くにある視覚的な証拠を返します。
• **セルフホスト可能で MIT ライセンス：**アカウント、ホスト型の中継サービス、マネージドストレージ、ベンダーロックインは不要です。

すでに tube-bridge をお使いの皆さん、ありがとうございます。時間の節約に役立ったら、リポジトリにスターを付けることをご検討ください。ほかの人がこのプロジェクトを見つけやすくなり、同様の取り組みを続ける励みになります。

1 分で接続

最も簡単なセットアップでは、uvx を使用します。公開されている PyPI パッケージを分離された環境で実行できます。

uvx tube-bridge

通常、このコマンドは MCP クライアントが起動します。以下からクライアントを選んでください。

メモ

tube-bridge には Python 3.12 以降が必要です。API キーは任意です。ffmpeg が必要なのは youtube_get_frame のみです。また、最初の埋め込み処理ではローカルモデルがダウンロードされる場合があります。

Claude Desktop

Settings → Developer → Edit Config を開き、次の内容を追加します。

{
  "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

これにより、1 つのステータスツールと、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 が返す絶対パスに置き換えてください。

リサーチのワークフローを一通り試す

エージェントに次のように依頼します。

ローカル優先の AI エージェントに関する最近の動画を YouTube で検索してください。最も有力な検索結果の文字起こしを読み、local-agents という名前のコーパスに追加して、メモリについて議論している箇所を見つけ、タイムスタンプ付きのソースリンクを返し、その時点のフレームを抽出してください。

エージェントは次のツールの手順で依頼を完了できます。

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 を 1 枚返します
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 を実行するマシン上で行われます。

• ストレージ： ~/.tube_bridge/corpus.db の SQLite と sqlite-vec
• 埋め込み： fastembed を通じた BGE-small-en-v1.5
• チャンク化： 20 秒の重複を含む 80 秒のウィンドウ
• ランキング： 重複部分の除外と、ソースを考慮した動画ごとの上限
• 結果： 類似度スコア、時間範囲、動画タイトル、正規 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 として 1 枚返した後、一時メディアを削除します。フレームやクリップのライブラリは作成しません。

その他の実行方法

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 レジストリ

レジストリ名：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	いいえ	API のみで利用できる 3 つのツールを有効にし、対応する検索呼び出しを強化します
TUBE_BRIDGE_PROXY	いいえ	yt-dlp とトランスクリプトのリクエストを HTTP(S) または SOCKS プロキシ経由で送信します
TUBE_BRIDGE_CACHE	いいえ	cache.db と corpus.db を含むディレクトリを変更します
TUBE_BRIDGE_AUTH_KEY	いいえ	セルフホスト可能な HTTP MCP ルートを静的 Bearer トークンで保護します

仕組み

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 Plugin プレビュー

GitHub Releases には、以下を含む tube-bridge-agent-plugin-<version>.zip が含まれています。

• ローカル stdio MCP 設定
• tube-bridge-research スキル
• 調査用テンプレートと情報源の評価ガイダンス

Agent Plugins v1 では、依存関係のインストール方法は標準化されていません。プラグインホストが使用する環境に、Python 3.12 以降、ffmpeg、パッケージの依存関係をインストールしてください。このバンドルに認証情報は含まれていません。

既知の制限事項

• YouTube は、特にクラウドホスティングの IP 範囲からの匿名の yt-dlp リクエストやトランスクリプトのリクエストを制限することがあります。
• 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 をご覧ください。