VidWords YouTube

Busca la transcripción de un video de YouTube y lee sus fotogramas: cada respuesta cita una marca de tiempo en la que se puede hacer clic.

GitHub

Documentación

Servidor MCP de VidWords YouTube

Un servidor Model Context Protocol alojado que permite a un agente de IA leer videos de YouTube — y citar el segundo exacto del que obtuvo la respuesta.

Un modelo de lenguaje no puede ver un video. Apúntalo a este endpoint y obtiene trece herramientas para buscar transcripciones, buscar en los videos que ya has guardado, leer los fotogramas de un video — diapositivas, gráficos, demos, texto en pantalla — y responder preguntas con citas que se verifican antes de que las veas.

Sin código de integración. Sin scraping. Sin grupo de proxies.

https://vidwords.com/mcp

Esa URL es toda la configuración. Los clientes inician sesión mediante OAuth — sin necesidad de buscar o pegar una clave — y los que no tienen interfaz pueden enviar Authorization: Basic <your-api-token> en su lugar.

Solo remoto y alojado — no hay nada que instalar o autoalojar. Este repositorio es el manifiesto público, la referencia de configuración y el rastreador de problemas para ese endpoint.

Inicio rápido

La mayoría de los clientes no necesitan ningún token. El servidor habla OAuth, por lo que el cliente se registra, te envía a VidWords para iniciar sesión y almacena una credencial que renueva por sí solo. Puedes crear la cuenta durante ese paso de inicio de sesión. El plan gratuito incluye 25 Solicitudes en la Nube y 200 Unidades de IA al mes, por lo que puedes configurarlo y usarlo antes de pagar nada.

Claude (claude.ai y Claude Desktop)

Personalizar → Conectores, luego + Añadir → Añadir conector personalizado.
URL: https://vidwords.com/mcp
En las opciones del cliente OAuth, elige Registrar automáticamente. VidWords registra cada conector por sí mismo (registro dinámico de clientes), por lo que la opción predeterminada de "identidad publicada" de Claude no se conectará.
Conecta, inicia sesión en VidWords y aprueba.

En un plan de Equipo o Empresa, un propietario lo añade primero, en Configuración de la organización → Conectores → Añadir → Personalizado → Web; luego los miembros se conectan desde Personalizar → Conectores.

ChatGPT

En chatgpt.com, abre Plugins, selecciona + y luego Añadir servidor MCP personalizado.
Nombre: VidWords · URL del servidor: https://vidwords.com/mcp · Autenticación: OAuth.
Acepta la advertencia de riesgo y selecciona Crear como plugin, luego inicia sesión en VidWords y aprueba.
Instala el nuevo plugin, luego escribe @ en un chat y elige VidWords.

Hazlo en la web; en una cuenta de espacio de trabajo, un administrador puede necesitar permitir servidores MCP personalizados.

En cualquier caso, el host se registra, te envía a VidWords para iniciar sesión y muestra una pantalla de consentimiento que nombra exactamente lo que está solicitando. El registro solo no concede nada — el acceso comienza solo cuando una persona con sesión iniciada hace clic en Aprobar, y las conexiones activas se pueden revocar desde la página de API y MCP con efecto inmediato.

Claude Desktop desde un archivo de configuración

claude_desktop_config.json solo ejecuta servidores locales (stdio) — una entrada url remota allí no es compatible (y se ha informado que borra la sección mcpServers del archivo). Para declarar el servidor en el archivo de todos modos, conéctalo con mcp-remote, que ejecuta el mismo flujo de inicio de sesión en tu navegador — aún sin nada que pegar:

{
  "mcpServers": {
    "vidwords": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://vidwords.com/mcp"]
    }
  }
}

Cierra y vuelve a abrir Claude Desktop después de editar el archivo.

Claude Code

claude mcp add --transport http vidwords https://vidwords.com/mcp

Luego escribe /mcp en una sesión y elige Autenticar.

Cursor — un clic, o `.cursor/mcp.json`

Usa el botón Añadir a Cursor de arriba, o:

{
  "mcpServers": {
    "vidwords": {
      "url": "https://vidwords.com/mcp"
    }
  }
}

Cursor muestra el servidor como Necesita inicio de sesión — haz clic una vez y ejecutará el flujo OAuth en tu navegador. Como este archivo no contiene secretos, es seguro confirmarlo, lo que no ocurre con el formulario de encabezado de abajo.

VS Code

Usa el botón Añadir a VS Code de arriba, o pon esto en .vscode/mcp.json:

{
  "servers": {
    "vidwords": { "type": "http", "url": "https://vidwords.com/mcp" }
  }
}

VS Code te pedirá que inicies sesión la primera vez que se inicie el servidor.

Codex CLI

codex mcp add vidwords --url https://vidwords.com/mcp
codex mcp login vidwords

Un token estático en su lugar

Para CI, un contenedor o un cliente sin soporte OAuth, autentícate con un encabezado. Crea una cuenta en vidwords.com/register, verifica tu correo electrónico y luego crea una clave en la página de API y MCP. El valor de una clave se muestra una sola vez, cuando se crea.

Claude Code

claude mcp add --transport http vidwords https://vidwords.com/mcp \
  --header "Authorization: Basic YOUR_API_TOKEN"

Claude Desktop — `claude_desktop_config.json`

El mismo puente mcp-remote de arriba, con la clave en lugar del inicio de sesión. Mantén la clave en env: Claude Desktop en Windows (y Cursor, y el Codex CLI) no escapan los espacios dentro de args, por lo que Basic YOUR_API_TOKEN escrito allí se divide en dos — la solución del propio README de mcp-remote:

{
  "mcpServers": {
    "vidwords": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://vidwords.com/mcp",
               "--header", "Authorization:${VIDWORDS_MCP_AUTH}"],
      "env": { "VIDWORDS_MCP_AUTH": "Basic YOUR_API_TOKEN" }
    }
  }
}

Cursor — `.cursor/mcp.json`

{
  "mcpServers": {
    "vidwords": {
      "url": "https://vidwords.com/mcp",
      "headers": { "Authorization": "Basic YOUR_API_TOKEN" }
    }
  }
}

Mantén esto fuera del control de versiones, o usa ~/.cursor/mcp.json en su lugar — el encabezado contiene una credencial activa.

Codex CLI — `~/.codex/config.toml`

[mcp_servers.vidwords]
url = "https://vidwords.com/mcp"
env_http_headers = { "Authorization" = "VIDWORDS_MCP_AUTH" }

export VIDWORDS_MCP_AUTH="Basic YOUR_API_TOKEN"

No uses bearer_token_env_var. Es el campo de apariencia obvia, pero envía Authorization: Bearer <value> y este servidor se autentica con Basic.

Clientes sin soporte de encabezados personalizados, y Docker

Este repositorio también incluye un pequeño proxy stdio (src/index.js) que habla MCP en stdin/stdout y reenvía las llamadas de herramientas al endpoint alojado. Úsalo cuando tu cliente no pueda enviar un encabezado HTTP personalizado, o cuando quieras el servidor en un contenedor:

{
  "mcpServers": {
    "vidwords": {
      "command": "npx",
      "args": ["-y", "github:haljishi/vidwords-mcp"],
      "env": { "VIDWORDS_API_TOKEN": "YOUR_API_TOKEN" }
    }
  }
}

Ejecuta directamente desde este repositorio — el proxy no está publicado en npm, por lo que un npx @vidwords/mcp simple no se resolverá.

docker build -t vidwords-mcp .
docker run --rm -i -e VIDWORDS_API_TOKEN=YOUR_API_TOKEN vidwords-mcp

Los esquemas de las herramientas se declaran en línea en el proxy, por lo que initialize y tools/list responden sin ninguna credencial. El descubrimiento de recursos también es local; el upstream se contacta cuando se solicita una herramienta, un prompt o un recurso de interfaz. El proxy también expone los recursos de MCP Apps de análisis y cuenta. Los hosts compatibles pueden renderizar tarjetas interactivas; la tarjeta de análisis incluye Mostrar análisis completo. Las lecturas de recursos de interfaz y las llamadas de herramientas usan el mismo upstream autenticado, y los resultados estructurados pasan sin cambios.

Una llamada sin VIDWORDS_API_TOKEN devuelve un error legible en lugar de fallar el protocolo de enlace. VIDWORDS_MCP_URL anula el endpoint si apuntas a una instancia que no es de producción.

El puente genérico mcp-remote también funciona:

{
  "mcpServers": {
    "vidwords": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://vidwords.com/mcp",
               "--header", "Authorization:${VIDWORDS_MCP_AUTH}"],
      "env": { "VIDWORDS_MCP_AUTH": "Basic YOUR_API_TOKEN" }
    }
  }
}

Los archivos de configuración listos viven en examples/.

Las trece herramientas

Dos saldos las pagan: una Solicitud en la Nube obtiene la transcripción de un video, y las Unidades de IA pagan por leer fotogramas y por transcribir audio — un análisis de fotogramas nuevo gasta uno de cada tipo: 1 Solicitud en la Nube por su transcripción, más Unidades de IA por minuto de video. Un video que la cuenta ya ha obtenido está en su Biblioteca, y leerlo de nuevo es gratis — otro rango de tiempo, otra página, una búsqueda después de una obtención. Cada resultado medido informa lo que charged.

Herramienta	Qué hace	Costo
`search_transcript`	Encuentra dónde un video discute algo. Toma un video o una lista de hasta 25, por lo que una llamada puede responder una pregunta en todo un canal. Devuelve los momentos coincidentes con marcas de tiempo, contexto citado y enlaces profundos `youtube.com/watch?v=…&t=…s`. Opcional `from`/`to`.	1 Solicitud en la Nube por video nuevo
`get_transcript`	Texto de transcripción para hasta 25 videos, o el intervalo entre dos códigos de tiempo. `lang` elige una pista de subtítulos, `maxChars` pagina una transcripción larga, `source: "audio"` transcribe el habla en sí.	1 Solicitud en la Nube por video nuevo
`search_library`	Búsqueda de texto completo en todas las transcripciones que la cuenta ya ha guardado, con marcas de tiempo y enlaces profundos.	Gratis
`list_library`	Los videos guardados de la cuenta, del más reciente al más antiguo, más el ID de análisis terminado más reciente.	Gratis
`list_analyses`	Análisis de IA Watch guardados con IDs, estado y enlaces de resultados; admite paginación y filtrado por video.	Gratis
`list_languages`	Las pistas de subtítulos que tiene un video y cuáles son generadas automáticamente (el habla) frente a las subidas (posiblemente traducciones).	Gratis
`list_channel_videos`	Resuelve un identificador de canal, URL o id `UC…` a sus subidas recientes.	1 Solicitud en la Nube · Starter y superiores
`list_watchlists`	Las listas de seguimiento de Radar de la cuenta y cuánto ha grabado cada una.	Gratis
`watchlist_activity`	Subidas más recientes que Radar ha grabado para una lista de seguimiento.	Gratis
`account`	Plan y ambos saldos, para que el agente pueda calcular el precio de un trabajo antes de ejecutarlo.	Gratis
`analyze_video`	Inicia un análisis a nivel de fotogramas — diapositivas, gráficos, demos y texto en pantalla, no solo subtítulos. Devuelve un `analysisId` inmediatamente. `mode` es `quick`, `smart`, `deep` o `auto`; Deep se ejecuta en cualquier plan con suficientes Unidades de IA. `estimateOnly: true` devuelve el precio en su lugar, sin iniciar nada.	1 Solicitud en la Nube, luego Unidades de IA por minuto: Quick 2.8, Standard 4, Deep 30 · estimación gratis
`get_analysis`	Lee un análisis terminado: resumen, capítulos, puntos clave, evidencia con marca de tiempo y pasos. Omite `analysisId` para abrir el último resultado terminado. `waitSeconds` (hasta 25) mantiene la llamada hasta que esté listo en lugar de sondear.	Gratis
`ask_video`	Haz una pregunta contra un análisis terminado. Las citas se verifican contra la evidencia almacenada o se descartan.	6 Unidades de IA por pregunta

Revisa la Biblioteca primero

search_library y list_library leen lo que la cuenta ya tiene, sin costo. Un agente que busca en la Biblioteca antes de obtener un video de nuevo responde "¿qué dijo esa entrevista que vi la semana pasada sobre precios?" sin gastar nada y sin el viaje de ida y vuelta.

Prefiere `search_transcript` sobre `get_transcript`

Ambos cuestan una Solicitud en la Nube por video nuevo, por lo que no hay razón de facturación para elegir. La razón es el contexto. Pregunta "¿qué dijo esta entrevista de dos horas sobre precios?" y get_transcript devuelve aproximadamente 20,000 palabras, de las cuales quizás 300 son sobre precios — esas 300 ahora compiten por atención con 19,700 que no lo son, y la respuesta empeora, se vuelve más lenta y más costosa de generar.

search_transcript devuelve solo los tramos coincidentes, cada uno con un enlace profundo. Recurre a get_transcript cuando realmente quieras el texto completo: una exportación, un diff, un corpus.

Pide un intervalo, no un video completo

Ambas herramientas de transcripción aceptan códigos de tiempo opcionales from y to — segundos (615), m:ss (10:20) o h:mm:ss (1:02:13):

{ "videos": ["dQw4w9WgXcQ"], "from": "10:20", "to": "11:00" }

Estos son los mismos formatos que las herramientas imprimen, por lo que una marca de tiempo de una respuesta se puede pegar directamente en la siguiente pregunta. Un código de tiempo que no se puede analizar se rechaza antes de obtener nada, por lo que un error tipográfico no cuesta nada — nunca se amplía silenciosamente a todo el video.

Pagina una transcripción larga en lugar de adivinar rangos

get_transcript toma maxChars. Un resultado cortado dice truncated: true y lleva nextFrom, el segundo para continuar; pásalo de vuelta como from. El corte siempre cae entre subtítulos, y cada página después de la primera es una relectura de un video ya en la Biblioteca — gratis.

{ "videos": ["dQw4w9WgXcQ"], "maxChars": 20000 }

Qué idioma obtuviste y por qué

El idioma de una pista de subtítulos no es necesariamente el idioma hablado. Una pista generada automáticamente transcribe el habla; una subida puede ser una traducción — algunos videos llevan una docena de traducciones de la comunidad y ninguna pista en el idioma realmente hablado. Por lo tanto, cada transcripción dice por qué es la pista que es:

selectionReason: requested, spoken_language (coincide con el habla), caption_fallback (no se conoce ninguna pista que coincida con el habla — el inglés, si está presente, se eligió por legibilidad), translated o audio_transcription.
spokenLanguage: el idioma que se habla cuando se conoce; de lo contrario, null — no es una suposición.
lang solicita una pista. Si el video no tiene ninguna en ese idioma, get_transcript responde language_unavailable con la availableLanguages que sí tiene, y no cobra nada.
source: "audio" transcribe lo que se dice en lugar de leer los subtítulos — la forma de obtener las palabras originales cuando cada subtítulo es una traducción. Se cobra como cualquier transcripción de audio (3 unidades de IA por minuto de video, además de la solicitud en la nube) y pasarlo es el consentimiento.

list_languages responde la misma pregunta de forma gratuita, a partir de lo que ya está almacenado.

Una llamada a través de un canal

search_transcript acepta una lista, que es como se responde "¿qué ha dicho este canal sobre X" sin un viaje de ida y vuelta por video. Obtén los ids de list_channel_videos primero:

{ "video": ["VIDEO_ID_1", "VIDEO_ID_2", "VIDEO_ID_3"], "query": "pricing" }

Cada video nuevo se factura con la habitual 1 solicitud en la nube, y un video no disponible se informa en su propia fila en lugar de hacer fallar la llamada — los demás se obtuvieron y se cobraron, así que aún los recibes.

Lee la imagen, no solo los subtítulos

analyze_video examina diapositivas, gráficos, ejemplos de código y texto en pantalla que nunca se dice en voz alta. ask_video luego responde basándose en ese análisis almacenado, y cada cita se verifica antes de que la veas: una afirmación visual debe coincidir con un fotograma que realmente se grabó, una afirmación hablada debe aterrizar en un segmento real de la transcripción. Cualquier cosa que falle se descarta, y cuando nada sobrevive, la respuesta dice que la evidencia es insuficiente en lugar de producir una suposición confiada.

Eso es ocasionalmente molesto — una negativa es una demostración peor que una respuesta fluida — y es la única versión de esta función que es segura de poner frente a un agente, porque un agente repite lo que se le dice sin el escepticismo que aplica un lector humano.

Autenticación, costos y límites

Si pegaste un token: Basic, no Bearer. El token se envía tal cual; no codificas en base64 un par user:pass. Los clientes que iniciaron sesión llevan su propia credencial y esto no aplica.
Verifica tu correo primero. Hasta que hagas clic en el enlace de verificación, cada llamada devuelve 403 con {"error":"email_unverified"} — la falla más común en la primera llamada en una cuenta nueva.
Los saldos se comparten con la API REST y el sitio web. Una solicitud en la nube es una nueva transcripción; el análisis de fotogramas gasta 1 solicitud en la nube más unidades de IA, y la transcripción de audio gasta unidades de IA además de su solicitud en la nube. Una ejecución rechazada antes de que comience no cuesta nada, y analyze_video con estimateOnly: true cotiza el precio de forma gratuita.
Límite de tasa por minuto, según el plan: Gratis 60, Inicial 200, Pro 500, Equipo 1,000 solicitudes. El servidor no tiene estado, por lo que un cliente vuelve a ejecutar initialize antes de cada llamada y una llamada de herramienta es varias solicitudes. analyze_video tiene su propio límite de 10 inicios por minuto, compartido con la ruta REST.
Los tokens de RapidAPI se rechazan aquí. Esa identidad se mide por llamada y no tiene cuenta detrás, y ninguna de las dos sobrevive a una sesión de llamadas de herramientas. Usa un token de API de VidWords.
Sin estado por diseño. Sin flujos SSE reanudables, sin sesión que eliminar; cada herramienta responde en una sola vez. GET y DELETE devuelven un error JSON-RPC en lugar de un HTML 404.
Sin subtítulos, o los incorrectos. Para un video sin pista de subtítulos, pasa transcribeAudio: true para transcribirlo desde el audio; para reemplazar subtítulos que existen (todas las traducciones subidas, por ejemplo), pasa source: "audio". Ambos son funciones de pago, con precio por minuto de video, y nunca se ejecutan sin que se soliciten.

Números completos: precios.

Prompts

El servidor también publica tres prompts, que clientes como Claude muestran como acciones listas para usar. Cada uno le dice al modelo qué herramientas usar y en qué orden, primero las más baratas.

Prompt	Argumentos	Qué hace
`summarize_video`	`video`	Un resumen con marcas de tiempo de un video, leído de la forma más barata disponible.
`research_channel`	`channel`, `topic`	Lo que un canal ha dicho sobre un tema, con momentos citados.
`find_in_my_library`	`topic`	Busca todo lo ya guardado — gratis.

Habilidad de agente

skills/youtube-transcripts/SKILL.md es una habilidad de agente lista para usar para este servidor — selección de herramientas, intervalos de códigos de tiempo, búsqueda en todo el canal, la tabla de costos y los códigos de error que vale la pena atender, en el formato que Claude y los agentes compatibles cargan directamente.

Copia la carpeta en el directorio de habilidades de tu agente:

git clone --depth 1 https://github.com/haljishi/vidwords-mcp
cp -r vidwords-mcp/skills/youtube-transcripts ~/.claude/skills/

Asume que el servidor MCP está configurado (ver Inicio rápido). El punto es que un asistente que ha leído la habilidad sabe recurrir a search_transcript con un intervalo de códigos de tiempo en lugar de traer una transcripción completa de dos horas a su contexto.

Documentación

Soporte

Abre un problema aquí para cualquier cosa sobre la superficie MCP — una herramienta que se comporta mal, un cliente cuya configuración no hemos documentado, un esquema que podría ser más claro. Las preguntas de cuenta y facturación van a soporte.

Licencia

El contenido de este repositorio (documentación y ejemplos de configuración) tiene licencia MIT. El servicio alojado en sí es propietario y se rige por los términos de VidWords.

Producto independiente; no afiliado con YouTube o Google.

VidWords YouTube

Documentación

Servidor MCP de VidWords YouTube

Inicio rápido

Claude (claude.ai y Claude Desktop)

ChatGPT

Claude Desktop desde un archivo de configuración

Claude Code

Cursor — un clic, o .cursor/mcp.json

VS Code

Codex CLI

Un token estático en su lugar

Claude Code

Claude Desktop — claude_desktop_config.json

Cursor — .cursor/mcp.json

Codex CLI — ~/.codex/config.toml

Clientes sin soporte de encabezados personalizados, y Docker

Las trece herramientas

Revisa la Biblioteca primero

Prefiere search_transcript sobre get_transcript

Pide un intervalo, no un video completo

Pagina una transcripción larga en lugar de adivinar rangos

Qué idioma obtuviste y por qué

Una llamada a través de un canal

Lee la imagen, no solo los subtítulos

Autenticación, costos y límites

Prompts

Habilidad de agente

Documentación

Soporte

Licencia

Cursor — un clic, o `.cursor/mcp.json`

Claude Desktop — `claude_desktop_config.json`

Cursor — `.cursor/mcp.json`

Codex CLI — `~/.codex/config.toml`

Prefiere `search_transcript` sobre `get_transcript`