tube-bridge

Servidor MCP de pesquisa no YouTube auto-hospedado com 17 ferramentas para busca, transcrições, frames com timestamp, comentários e corpora semânticos locais privados.

GitHub

Documentação

tube-bridge

Pesquisa do YouTube auto-hospedada para agentes de IA.

Pesquise vídeos e canais, leia transcrições e comentários, extraia quadros com carimbo de data/hora e construa corpora privados de busca semântica — por meio de 17 ferramentas MCP.

14 das 17 ferramentas não precisam de chave da API do YouTube.
Corpus local primeiro: transcrições, vetores e índices permanecem na sua máquina.
Resultados de pesquisa úteis: títulos, pontuações de similaridade, URLs canônicas de vídeo e links com carimbo de data/hora.
Uma ferramenta para um quadro: retorne evidência visual perto de um achado de transcrição sem manter arquivos de mídia.
Auto-hospedado e MIT: sem conta, intermediário hospedado, armazenamento gerenciado ou dependência de fornecedor.

Agradecemos a todos que já usam o tube-bridge. Se ele economizar seu tempo, considere dar uma estrela no repositório — isso ajuda outras pessoas a descobrirem o projeto e sinaliza que publicar mais trabalhos como este vale a pena.

Conecte-se em um minuto

A configuração mais simples usa uvx, que executa o pacote PyPI publicado em um ambiente isolado:

uvx tube-bridge

Normalmente, seu cliente MCP inicia esse comando para você. Escolha seu cliente abaixo.

[!NOTE] O tube-bridge requer Python 3.12 ou mais recente. Uma chave de API é opcional. ffmpeg é necessária apenas para youtube_get_frame, e a primeira operação de incorporação pode baixar o modelo local.

Claude Desktop

Abra Configurações → Desenvolvedor → Editar Config e adicione:

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

Reinicie o Claude Desktop após salvar a configuração.

Claude Code

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

Cursor

Crie .cursor/mcp.json no seu projeto, ou adicione o servidor à sua configuração MCP de nível de usuário:

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

VS Code

Crie .vscode/mcp.json:

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

Codex CLI

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

Pacote Pi

O Pi pode carregar o adaptador relativo ao pacote e a habilidade canônica tube-bridge-research da mesma fonte Git:

python3 -m pip install tube-bridge==1.1.6
pi install git:github.com/TheWhiteWater/tube-bridge@v1.1.6
pi list

Isso registra uma ferramenta de status mais todas as 17 ferramentas MCP com o prefixo tube_bridge_. O adaptador lê os plugin.json e mcp.json existentes, inicia apenas o runtime stdio local, preserva conteúdo de texto e imagem limitado e encaminha apenas um ambiente de processo filho na lista de permissões.

O gerenciador de pacotes Pi instala a dependência do adaptador Node, mas não instala Python ou ffmpeg. Garanta que o python3 visível para o Pi seja Python 3.12+ com as dependências do tube-bridge instaladas; instale ffmpeg separadamente para usar youtube_get_frame. Por padrão, o estado gerenciado pelo Pi fica sob o diretório de dados da plataforma; defina TUBE_BRIDGE_PI_DATA para mover essa raiz. Um TUBE_BRIDGE_CACHE explícito ainda tem precedência para os bancos de dados de runtime. A porta opcional de quadro ao vivo é /tube-bridge-selftest frame.

Remova o pacote com:

pi remove git:github.com/TheWhiteWater/tube-bridge@v1.1.6

Se um cliente de desktop não conseguir encontrar uvx, substitua "uvx" pelo caminho absoluto retornado por which uvx no macOS/Linux ou where.exe uvx no Windows.

Experimente o fluxo de pesquisa completo

Pergunte ao seu agente:

Pesquise no YouTube vídeos recentes sobre agentes de IA locais primeiro. Leia a transcrição do resultado mais forte, adicione-a a um corpus chamado local-agents, encontre a seção que discute memória, retorne o link da fonte com carimbo de data/hora e extraia um quadro desse momento.

O agente pode concluir essa solicitação com esta sequência de ferramentas:

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)

Adicione mais vídeos com corpus_add e depois use corpus_search para pesquisar em todas as transcrições de uma vez.

Ferramentas

Ferramenta	Chave da API do YouTube	O que faz
`youtube_search`	Opcional	Pesquise vídeos com filtros de data, canal, duração e ordenação
`youtube_get_video_info`	Opcional	Obtenha título, duração, visualizações, canal, descrição e tags
`youtube_get_trending`	Opcional	Obtenha vídeos em alta no momento
`youtube_get_channel_videos`	Não	Obtenha uploads recentes de uma URL de canal ou `@handle`
`youtube_get_playlist`	Não	Obtenha vídeos de uma playlist
`youtube_get_transcript`	Não	Obtenha uma transcrição, opcionalmente com carimbos de data/hora `[MM:SS]`
`youtube_get_frame`	Não	Retorne um JPEG efêmero perto de um carimbo de data/hora em milissegundos inteiros
`youtube_get_available_languages`	Não	Liste faixas de legenda manuais e geradas automaticamente
`youtube_get_comments`	Obrigatória	Obtenha comentários de nível superior com curtidas e contagens de respostas
`youtube_search_channels`	Obrigatória	Pesquise canais e filtre por contagem de inscritos
`youtube_get_channel_info`	Obrigatória	Obtenha estatísticas do canal, país e palavras-chave
`corpus_create`	Não	Crie um corpus local nomeado
`corpus_add`	Não	Busque, divida e incorpore localmente uma transcrição de vídeo
`corpus_search`	Não	Pesquise semanticamente um corpus com resultados com carimbo de data/hora
`corpus_list`	Não	Liste corpora com contagens de vídeos e trechos
`corpus_delete`	Não	Exclua permanentemente um corpus e seus vetores
`tube_bridge_help`	Não	Leia a documentação de runtime e limitações conhecidas

Não significa que nenhuma chave da API de dados do YouTube é necessária; o acesso à rede ao YouTube ainda pode ser necessário. Pesquisa, informações de vídeo e tendências funcionam sem chave por meio do yt-dlp e fazem upgrade para a API de dados v3 quando uma chave é configurada.

Chave opcional da API de dados do YouTube

Uma chave da API de dados do YouTube v3 desbloqueia comentários, pesquisa de canais e detalhes de canais. Ela também melhora a confiabilidade de pesquisa, informações de vídeo e tendências.

Crie uma chave no Google Cloud Console, ative a API de dados do YouTube v3 e exponha-a ao processo que inicia o tube-bridge:

export YOUTUBE_API_KEY="your-key"

Mantenha as chaves fora dos arquivos de configuração MCP commitados. Use o suporte a segredos/ambiente do seu cliente quando disponível.

Corpus semântico local

O armazenamento do corpus e a inferência de incorporação são locais à máquina que executa o tube-bridge.

Armazenamento: SQLite mais sqlite-vec em ~/.tube_bridge/corpus.db
Incorporações: BGE-small-en-v1.5 por meio do fastembed
Divisão: janelas de 80 segundos com sobreposição de 20 segundos
Classificação: deduplicação de sobreposição e limites por vídeo cientes da fonte
Resultados: pontuação de similaridade, intervalo de tempo, título do vídeo, URL canônica e URL com carimbo de data/hora

Defina TUBE_BRIDGE_CACHE para mover tanto o corpus quanto os bancos de dados de cache:

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

O modelo de incorporação pode ser baixado no primeiro uso. Após os ativos estarem disponíveis, a inferência de incorporação não requer uma API de modelo externa.

Extração de quadros

youtube_get_frame requer ffmpeg em PATH; a imagem Docker já o inclui.

Cada chamada baixa uma seção temporária curta ao redor de timestamp_ms, retorna um JPEG limitado como MCP ImageContent e remove a mídia temporária antes de retornar. Ela não cria uma biblioteca de quadros ou clipes.

Outras formas de executar

Instalação PyPI persistente

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

O endpoint de saúde é http://localhost:8080/health; o endpoint HTTP Streamable é http://localhost:8080/mcp.

Registro MCP oficial

Nome do registro: io.github.TheWhiteWater/tube-bridge

Clientes cientes do registro podem instalar a distribuição PyPI com uvx e iniciar o servidor stdio sem um intermediário hospedado.

Configuração HTTP remota

Para uma instância HTTP que você opera:

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

Proteja rotas MCP remotas definindo uma chave Bearer no lado do servidor:

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

Em seguida, configure um cliente com suporte a cabeçalhos:

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

/health permanece público. /mcp, /sse e /messages exigem a chave Bearer quando TUBE_BRIDGE_AUTH_KEY está definido. O SSE legado está disponível em /sse para clientes que ainda precisam dele.

Variáveis de ambiente

Variável	Obrigatória	Propósito
`YOUTUBE_API_KEY`	Não	Ativa as 3 ferramentas somente de API e melhora as chamadas de descoberta suportadas
`TUBE_BRIDGE_PROXY`	Não	Roteia solicitações de yt-dlp e transcrição por um proxy HTTP(S) ou SOCKS
`TUBE_BRIDGE_CACHE`	Não	Altera o diretório que contém `cache.db` e `corpus.db`
`TUBE_BRIDGE_AUTH_KEY`	Não	Protege rotas MCP HTTP auto-hospedadas com um token Bearer estático

Como funciona

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 é recomendado para clientes locais;
HTTP Streamable está disponível em /mcp para uso remoto auto-hospedado;
respostas de fallback bem-sucedidas mantêm seus esquemas normais;
falhas controladas usam erros MCP tipados com campos estáveis code, source e retryable;
bancos de dados de cache e corpus são separados e permanecem de propriedade do operador.

Prévia do Agent Plugin

GitHub Releases inclui tube-bridge-agent-plugin-<version>.zip, contendo:

a configuração MCP stdio local;
a habilidade tube-bridge-research;
modelos de pesquisa e orientação de avaliação de fontes.

O Agent Plugins v1 não padroniza a instalação de dependências. Instale Python 3.12+, ffmpeg e as dependências do pacote no ambiente usado pelo host do plugin. O pacote não contém credenciais.

Limitações conhecidas

O YouTube pode restringir solicitações anônimas de yt-dlp e transcrição, especialmente de faixas de IP de hospedagem em nuvem.
Uma chave da API de dados melhora a confiabilidade de descoberta e metadados, mas não substitui o acesso a transcrições.
A configuração inicial do modelo de incorporação local pode exigir acesso à rede e espaço adicional em disco.
O tube-bridge é software auto-hospedado; ele não fornece contas, acesso hospedado público, armazenamento gerenciado ou SLA.

Se o YouTube bloquear solicitações da sua rede, defina TUBE_BRIDGE_PROXY. Mantenha as credenciais de proxy em variáveis de ambiente em vez de configuração commitada.

Desenvolvimento

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 é um teste de fumaça opcional do YouTube ao vivo. A suíte de testes determinística não chama o YouTube.

Veja CONTRIBUTING.md para contribuir. Relatórios de segurança devem seguir SECURITY.md.

Licença

MIT — veja LICENSE.