VidWords YouTube

Pesquise a transcrição de um vídeo do YouTube e leia seus quadros — cada resposta cita um timestamp clicável.

Documentação

Servidor MCP VidWords YouTube

Um servidor Model Context Protocol hospedado que permite a um agente de IA ler vídeos do YouTube — e citar o segundo exato em que obteve a resposta.

Um modelo de linguagem não consegue assistir a um vídeo. Aponte-o para este endpoint e ele ganha nove ferramentas para buscar transcrições, ler os frames de um vídeo — slides, gráficos, demonstrações, texto na tela — e responder perguntas com citações que são verificadas antes que você as veja.

Sem código de integração. Sem scraping. Sem pool de proxies.

POST https://vidwords.com/mcp
Authorization: Basic <your-api-token>

Somente remoto e hospedado — não há nada para instalar ou auto-hospedar. Este repositório é o manifesto público, a referência de configuração e o rastreador de problemas para esse endpoint.

Início rápido

Obtenha um token gratuito: crie uma conta em vidwords.com/register, verifique seu e-mail e copie o token do seu perfil. O plano gratuito inclui créditos mensais e 10 minutos de Watch, então você pode configurar isso e usar antes de pagar qualquer coisa.

Claude Code

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

Claude Desktop — `claude_desktop_config.json`

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

Cursor — `.cursor/mcp.json`

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

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"

Não use bearer_token_env_var. É o campo de aparência óbvia, mas ele envia Authorization: Bearer <value> e este servidor autentica com Basic.

claude.ai e ChatGPT — OAuth, nada para colar

Adicione https://vidwords.com/mcp como um conector personalizado. O host se registra, envia você para o VidWords para fazer login e mostra uma tela de consentimento nomeando exatamente o que está pedindo. O registro sozinho não concede nada — o acesso começa apenas quando uma pessoa conectada clica em Aprovar, e as conexões ativas podem ser revogadas na sua página de API com efeito imediato.

Clientes sem suporte a cabeçalhos personalizados e Docker

Este repositório também inclui um pequeno proxy stdio (src/index.js) que fala MCP em stdin/stdout e encaminha chamadas de ferramentas para o endpoint hospedado. Use-o quando seu cliente não puder enviar um cabeçalho HTTP personalizado, ou quando quiser o servidor em um contêiner:

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

Execute diretamente deste repositório — o proxy não é publicado no npm, então um npx @vidwords/mcp simples não será resolvido.

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

Os esquemas das ferramentas são declarados inline no proxy, então initialize e tools/list respondem sem nenhuma credencial e o upstream não é contatado até que uma ferramenta seja realmente chamada. Uma chamada sem VIDWORDS_API_TOKEN retorna um erro legível em vez de falhar no handshake. VIDWORDS_MCP_URL substitui o endpoint se você estiver apontando para uma instância que não seja de produção.

A ponte genérica mcp-remote também funciona:

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

Arquivos de configuração prontos estão em examples/.

As nove ferramentas

Ferramenta	O que faz	Custo
`search_transcript`	Encontra onde um vídeo discute algo. Aceita um vídeo ou uma lista de até 25, então uma chamada pode responder a uma pergunta em todo um canal. Retorna os momentos correspondentes com timestamps, contexto citado e links profundos `youtube.com/watch?v=…&t=…s`.	1 crédito por vídeo
`get_transcript`	Texto completo da transcrição para até 25 vídeos em uma chamada.	1 crédito por vídeo
`list_channel_videos`	Resolve um handle de canal, URL ou id `UC…` para seus uploads recentes.	Grátis · Starter e acima
`list_watchlists`	As listas de watchlists do Radar da conta e quanto cada uma registrou.	Grátis
`watchlist_activity`	Uploads mais recentes que o Radar registrou para uma watchlist.	Grátis
`account`	Plano e créditos restantes, para o agente precificar um trabalho antes de executá-lo.	Grátis
`analyze_video`	Inicia uma análise em nível de frame — slides, gráficos, demonstrações e texto na tela, não apenas legendas. Retorna um `analysisId` imediatamente.	Minutos de Watch
`get_analysis`	Lê uma análise concluída: capítulos, pontos-chave, evidências com timestamp.	Grátis
`ask_video`	Faz uma pergunta contra uma análise concluída. As citações são verificadas contra evidências armazenadas ou descartadas.	1 pergunta de Watch

Prefira `search_transcript` em vez de `get_transcript`

Ambos custam um crédito por vídeo, então não há razão de cobrança para escolher. A razão é contexto. Pergunte "o que esta entrevista de duas horas disse sobre preços?" e get_transcript retorna aproximadamente 20.000 palavras, das quais talvez 300 sejam sobre preços — essas 300 agora competem por atenção com 19.700 que não são, e a resposta fica pior, mais lenta e mais cara de gerar.

search_transcript retorna apenas os trechos correspondentes, cada um com um link profundo. Use get_transcript quando você realmente quiser o texto completo: uma exportação, um diff, um corpus.

Peça um intervalo, não um vídeo inteiro

Ambas as ferramentas de transcrição aceitam timecodes opcionais from e to — segundos (615), m:ss (10:20) ou h:mm:ss (1:02:13):

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

Esses são os mesmos formatos que as ferramentas imprimem de volta, então um timestamp de uma resposta pode ser colado diretamente na próxima pergunta. Um timecode que não pode ser analisado é recusado antes que qualquer coisa seja buscada, então um erro de digitação não custa crédito — ele nunca amplia silenciosamente para o vídeo inteiro.

Uma chamada em todo um canal

search_transcript aceita uma lista, que é como você responde "o que este canal disse sobre X" sem uma ida e volta por vídeo. Obtenha os ids de list_channel_videos primeiro:

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

Cada vídeo é cobrado no usual 1 crédito, e um vídeo indisponível é relatado em sua própria linha em vez de falhar a chamada — os outros foram buscados e cobrados, então você ainda os recebe.

Ele lê a imagem, não apenas as legendas

analyze_video analisa slides, gráficos, exemplos de código e texto na tela que nunca é falado em voz alta. ask_video então responde com base nessa análise armazenada, e cada citação é verificada antes que você a veja: uma afirmação visual tem que corresponder a um frame que foi realmente gravado, uma afirmação falada tem que cair em um segmento real de transcrição. Qualquer coisa que falhar é descartada, e quando nada sobrevive, a resposta diz que a evidência é insuficiente em vez de produzir um palpite confiante.

Isso é ocasionalmente irritante — uma recusa é uma demonstração pior do que uma resposta fluente — e é a única versão desse recurso que é segura para colocar diante de um agente, porque um agente repete o que lhe é dito sem o ceticismo que um leitor humano aplica.

Autenticação, custo e limites

Basic, não Bearer. O token é enviado como está; você não codifica em base64 um par user:pass.
Verifique seu e-mail primeiro. Até você clicar no link de verificação, toda chamada retorna 403 com {"error":"email_unverified"} — a falha mais comum na primeira chamada em uma conta nova.
Os créditos são um único pool compartilhado com a API REST e o site. Um crédito é uma transcrição. A análise de frames consome minutos de Watch, e uma execução recusada antes de começar não custa nada.
Limite de taxa: 30 requisições / 10s — deliberadamente mais flexível que o 5 da API REST, porque o servidor é sem estado e um cliente reexecuta initialize antes de cada chamada. analyze_video tem seu próprio teto de 10 inícios por minuto, compartilhado com a rota REST.
Tokens RapidAPI são recusados aqui. Essa identidade é medida por chamada e não tem conta por trás, e nenhuma das duas coisas sobrevive a uma sessão de chamada de ferramentas. Use um token de API VidWords.
Sem estado por design. Sem streams SSE retomáveis, sem sessão para excluir; toda ferramenta responde em uma única vez. GET e DELETE retornam um erro JSON-RPC em vez de um HTML 404.
As legendas precisam existir. Para um vídeo sem faixa de legenda, uma conta conectada pode transcrever a partir do áudio — precificado por duração, cotado antes de você gastar.

Números completos: preços.

Habilidade do agente

skills/youtube-transcripts/SKILL.md é uma habilidade de agente pronta para uso para este servidor — seleção de ferramentas, intervalos de timecode, busca em todo o canal, a tabela de custos e os códigos de erro que valem a pena tratar, no formato que Claude e agentes compatíveis carregam diretamente.

Copie a pasta para o diretório de habilidades do seu agente:

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

Ele assume que o servidor MCP está configurado (veja Início rápido). O objetivo é que um assistente que leu a habilidade saiba usar search_transcript com um intervalo de timecode em vez de puxar uma transcrição inteira de duas horas para o seu contexto.

Documentação

Suporte

Abra um problema aqui para qualquer coisa sobre a superfície MCP — uma ferramenta que se comporta mal, um cliente cuja configuração não documentamos, um esquema que poderia ser mais claro. Perguntas sobre conta e cobrança vão para suporte.

Licença

O conteúdo deste repositório (documentação e exemplos de configuração) é licenciado sob MIT. O serviço hospedado em si é proprietário e regido pelos termos do VidWords.

Produto independente; não afiliado ao YouTube ou Google.

VidWords YouTube

Documentação

Servidor MCP VidWords YouTube

Início rápido

Claude Code

Claude Desktop — claude_desktop_config.json

Cursor — .cursor/mcp.json

Codex CLI — ~/.codex/config.toml

claude.ai e ChatGPT — OAuth, nada para colar

Clientes sem suporte a cabeçalhos personalizados e Docker

As nove ferramentas

Prefira search_transcript em vez de get_transcript

Peça um intervalo, não um vídeo inteiro

Uma chamada em todo um canal

Ele lê a imagem, não apenas as legendas

Autenticação, custo e limites

Habilidade do agente

Documentação

Suporte

Licença

Claude Desktop — `claude_desktop_config.json`

Cursor — `.cursor/mcp.json`

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

Prefira `search_transcript` em vez de `get_transcript`