tube-bridge

MCP de investigación de YouTube autoalojado con 17 herramientas para búsqueda, transcripciones, fotogramas con marca de tiempo, comentarios y corpus semánticos locales privados.

GitHub

Documentación

tube-bridge

Investigación de YouTube autoalojada para agentes de IA.

Busca videos y canales, lee transcripciones y comentarios, extrae fotogramas con marca de tiempo y construye corpus privados de búsqueda semántica — a través de 17 herramientas MCP.

14 de 17 herramientas no necesitan clave de API de YouTube.
Corpus local primero: las transcripciones, los vectores y los índices permanecen en tu máquina.
Resultados de investigación útiles: títulos, puntuaciones de similitud, URL canónicas de videos y enlaces con marca de tiempo.
Una herramienta para un fotograma: devuelve evidencia visual cerca de un hallazgo de transcripción sin conservar archivos multimedia.
Autoalojado y MIT: sin cuenta, intermediario alojado, almacenamiento gestionado ni bloqueo de proveedor.

Gracias a todos los que ya usan tube-bridge. Si te ahorra tiempo, considera darle una estrella al repositorio: ayuda a que otros descubran el proyecto y señala que vale la pena publicar más trabajo como este.

Conéctate en un minuto

La configuración más simple usa uvx, que ejecuta el paquete PyPI publicado en un entorno aislado:

uvx tube-bridge

Normalmente tu cliente MCP lanza ese comando por ti. Elige tu cliente a continuación.

[!NOTA] tube-bridge requiere Python 3.12 o más reciente. Una clave de API es opcional. ffmpeg solo se necesita para youtube_get_frame, y la primera operación de incrustación puede descargar el modelo local.

Claude Desktop

Abre Configuración → Desarrollador → Editar configuración y agrega:

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

Reinicia Claude Desktop después de guardar la configuración.

Claude Code

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

Cursor

Crea .cursor/mcp.json en tu proyecto, o agrega el servidor a tu configuración MCP a nivel de usuario:

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

VS Code

Crea .vscode/mcp.json:

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

Codex CLI

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

Paquete Pi

Pi puede cargar el adaptador relativo al paquete y la habilidad canónica tube-bridge-research desde la misma fuente Git:

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

Esto registra una herramienta de estado más las 17 herramientas MCP con el prefijo tube_bridge_. El adaptador lee los plugin.json y mcp.json existentes, lanza solo el runtime stdio local, conserva el contenido de texto e imagen limitado y reenvía solo un entorno de procesos secundarios en lista blanca.

El gestor de paquetes Pi instala la dependencia del adaptador Node pero no instala Python ni ffmpeg. Asegúrate de que el python3 visible para Pi sea Python 3.12+ con las dependencias de tube-bridge instaladas; instala ffmpeg por separado para usar youtube_get_frame. Por defecto, el estado gestionado por Pi vive bajo el directorio de datos de la plataforma; establece TUBE_BRIDGE_PI_DATA para mover esa raíz. Un TUBE_BRIDGE_CACHE explícito aún tiene prioridad para las bases de datos del runtime. La puerta opcional de fotogramas en vivo es /tube-bridge-selftest frame.

Elimina el paquete con:

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

Si un cliente de escritorio no puede encontrar uvx, reemplaza "uvx" con la ruta absoluta devuelta por which uvx en macOS/Linux o where.exe uvx en Windows.

Prueba el flujo de trabajo de investigación completo

Pregunta a tu agente:

Busca en YouTube videos recientes sobre agentes de IA locales primero. Lee la transcripción del resultado más fuerte, agrégalo a un corpus llamado local-agents, encuentra la sección que discute la memoria, devuelve el enlace fuente con marca de tiempo y extrae un fotograma de ese momento.

El agente puede completar esa solicitud con esta secuencia de herramientas:

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)

Agrega más videos con corpus_add, luego usa corpus_search para buscar en todas sus transcripciones a la vez.

Herramientas

Herramienta	Clave de API de YouTube	Qué hace
`youtube_search`	Opcional	Busca videos con filtros de fecha, canal, duración y orden
`youtube_get_video_info`	Opcional	Obtén título, duración, vistas, canal, descripción y etiquetas
`youtube_get_trending`	Opcional	Obtén videos en tendencia actualmente
`youtube_get_channel_videos`	No	Obtén subidas recientes de una URL de canal o `@handle`
`youtube_get_playlist`	No	Obtén videos de una lista de reproducción
`youtube_get_transcript`	No	Obtén una transcripción, opcionalmente con marcas de tiempo `[MM:SS]`
`youtube_get_frame`	No	Devuelve un JPEG efímero cerca de una marca de tiempo en milisegundos enteros
`youtube_get_available_languages`	No	Lista pistas de subtítulos manuales y generadas automáticamente
`youtube_get_comments`	Requerida	Obtén comentarios de nivel superior con me gusta y recuentos de respuestas
`youtube_search_channels`	Requerida	Busca canales y filtra por recuento de suscriptores
`youtube_get_channel_info`	Requerida	Obtén estadísticas del canal, país y palabras clave
`corpus_create`	No	Crea un corpus local con nombre
`corpus_add`	No	Obtiene, divide e incrusta localmente una transcripción de video
`corpus_search`	No	Busca semánticamente un corpus con resultados con marca de tiempo
`corpus_list`	No	Lista corpus con recuentos de videos y fragmentos
`corpus_delete`	No	Elimina permanentemente un corpus y sus vectores
`tube_bridge_help`	No	Lee documentación del runtime y limitaciones conocidas

No significa que no se necesita clave de API de datos de YouTube; el acceso de red a YouTube puede seguir siendo necesario. La búsqueda, la información de video y las tendencias funcionan sin clave a través de yt-dlp y se actualizan a Data API v3 cuando se configura una clave.

Clave opcional de API de datos de YouTube

Una clave de YouTube Data API v3 desbloquea comentarios, búsqueda de canales y detalles de canales. También mejora la búsqueda, la información de video y la fiabilidad de tendencias.

Crea una clave en Google Cloud Console, habilita YouTube Data API v3 y expónla al proceso que lanza tube-bridge:

export YOUTUBE_API_KEY="your-key"

Mantén las claves fuera de los archivos de configuración MCP confirmados. Usa el soporte de secretos/entorno de tu cliente cuando esté disponible.

Corpus semántico local

El almacenamiento del corpus y la inferencia de incrustación son locales a la máquina que ejecuta tube-bridge.

Almacenamiento: SQLite más sqlite-vec en ~/.tube_bridge/corpus.db
Incrustaciones: BGE-small-en-v1.5 a través de fastembed
División: ventanas de 80 segundos con superposición de 20 segundos
Clasificación: deduplicación de superposición y límites por video conscientes de la fuente
Resultados: puntuación de similitud, intervalo de tiempo, título del video, URL canónica y URL con marca de tiempo

Establece TUBE_BRIDGE_CACHE para mover tanto el corpus como las bases de datos de caché:

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

El modelo de incrustación puede descargarse en el primer uso. Después de que los activos estén disponibles, la inferencia de incrustación no requiere una API de modelo externa.

Extracción de fotogramas

youtube_get_frame requiere ffmpeg en PATH; la imagen Docker ya lo incluye.

Cada llamada descarga una sección temporal corta alrededor de timestamp_ms, devuelve un JPEG limitado como MCP ImageContent y elimina el medio temporal antes de devolver. No crea una biblioteca de fotogramas o clips.

Otras formas de ejecutar

Instalación persistente de 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

El endpoint de salud es http://localhost:8080/health; el endpoint Streamable HTTP es http://localhost:8080/mcp.

Registro MCP oficial

Nombre del registro: io.github.TheWhiteWater/tube-bridge

Los clientes conscientes del registro pueden instalar la distribución PyPI con uvx y lanzar el servidor stdio sin un intermediario alojado.

Configuración HTTP remota

Para una instancia HTTP que tú operas:

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

Protege las rutas MCP remotas estableciendo una clave Bearer del lado del servidor:

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

Luego configura un cliente capaz de encabezados:

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

/health permanece público. /mcp, /sse y /messages requieren la clave Bearer cuando TUBE_BRIDGE_AUTH_KEY está establecido. SSE heredado está disponible en /sse para clientes que aún lo necesiten.

Variables de entorno

Variable	Requerida	Propósito
`YOUTUBE_API_KEY`	No	Habilita las 3 herramientas solo de API y mejora las llamadas de descubrimiento compatibles
`TUBE_BRIDGE_PROXY`	No	Enruta solicitudes de yt-dlp y transcripciones a través de un proxy HTTP(S) o SOCKS
`TUBE_BRIDGE_CACHE`	No	Cambia el directorio que contiene `cache.db` y `corpus.db`
`TUBE_BRIDGE_AUTH_KEY`	No	Protege rutas MCP HTTP autoalojadas con un token Bearer estático

Cómo 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 se recomienda para clientes locales;
Streamable HTTP está disponible en /mcp para uso remoto autoalojado;
las respuestas de respaldo exitosas mantienen sus esquemas normales;
los fallos controlados usan errores MCP tipados con campos estables code, source y retryable;
las bases de datos de caché y corpus son separadas y permanecen propiedad del operador.

Vista previa del Plugin de Agente

GitHub Releases incluye tube-bridge-agent-plugin-<version>.zip, que contiene:

la configuración MCP stdio local;
la habilidad tube-bridge-research;
plantillas de investigación y guía de evaluación de fuentes.

Agent Plugins v1 no estandariza la instalación de dependencias. Instala Python 3.12+, ffmpeg y las dependencias del paquete en el entorno utilizado por el host del plugin. El paquete no contiene credenciales.

Limitaciones conocidas

YouTube puede restringir solicitudes anónimas de yt-dlp y transcripciones, especialmente desde rangos de IP de alojamiento en la nube.
Una clave de Data API mejora la fiabilidad del descubrimiento y los metadatos pero no reemplaza el acceso a transcripciones.
La configuración inicial del modelo de incrustación local puede requerir acceso de red y espacio adicional en disco.
tube-bridge es software autoalojado; no proporciona cuentas, acceso alojado público, almacenamiento gestionado ni un SLA.

Si YouTube bloquea solicitudes desde tu red, establece TUBE_BRIDGE_PROXY. Mantén las credenciales del proxy en variables de entorno en lugar de configuración confirmada.

Desarrollo

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 es una prueba de humo opcional de YouTube en vivo. El conjunto de pruebas determinista no llama a YouTube.

Consulta CONTRIBUTING.md para contribuir. Los informes de seguridad deben seguir SECURITY.md.

Licencia

MIT — consulta LICENSE.