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 treze ferramentas para buscar transcrições, pesquisar os vídeos que você já salvou, 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 de você vê-las.

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

https://vidwords.com/mcp

Essa URL é toda a configuração. Os clientes fazem login via OAuth — sem chave para encontrar ou colar — e os headless podem enviar Authorization: Basic <your-api-token> em vez disso.

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

A maioria dos clientes não precisa de token algum. O servidor fala OAuth, então o cliente se registra, envia você para o VidWords para fazer login e armazena uma credencial que ele renova sozinho. Você pode criar a conta durante essa etapa de login. O plano gratuito inclui 25 Cloud Requests e 200 AI Units por mês, então você pode configurar isso e usar antes de pagar qualquer coisa.

Claude (claude.ai e Claude Desktop)

Customize → Connectors, depois + Add → Add custom connector.
URL: https://vidwords.com/mcp
Nas opções do cliente OAuth, escolha Register automatically. O VidWords registra cada conector por conta própria (registro dinâmico de cliente), então a opção padrão "published identity" do Claude não vai conectar.
Conecte, faça login no VidWords e aprove.

Em um plano Team ou Enterprise, um proprietário adiciona primeiro, em Organization settings → Connectors → Add → Custom → Web; os membros então conectam a partir de Customize → Connectors.

ChatGPT

Em chatgpt.com, abra Plugins, selecione + e depois Add custom MCP server.
Nome: VidWords · URL do servidor: https://vidwords.com/mcp · Autenticação: OAuth.
Aceite o aviso de risco e selecione Create as a plugin, depois faça login no VidWords e aprove.
Instale o novo plugin e digite @ em um chat e escolha VidWords.

Faça isso na web; em uma conta de workspace, um administrador pode precisar permitir servidores MCP personalizados.

De qualquer forma, 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 somente quando uma pessoa conectada clica em Approve, e conexões ativas podem ser revogadas na página API & MCP com efeito imediato.

Claude Desktop a partir de um arquivo de configuração

claude_desktop_config.json só executa servidores locais (stdio) — uma entrada url remota lá não é suportada (e foi relatado que apaga a seção mcpServers do arquivo). Para declarar o servidor no arquivo mesmo assim, faça a ponte com mcp-remote, que executa o mesmo fluxo de login no seu navegador — ainda sem nada para colar:

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

Saia e reabra o Claude Desktop depois de editar o arquivo.

Claude Code

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

Depois digite /mcp em uma sessão e escolha Authenticate.

Cursor — um clique, ou `.cursor/mcp.json`

Use o botão Add to Cursor acima, ou:

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

O Cursor mostra o servidor como Needs login — clique uma vez e ele executa o fluxo OAuth no seu navegador. Como este arquivo não carrega segredo, é seguro fazer commit, o que o formulário de cabeçalho abaixo não é.

VS Code

Use o botão Add to VS Code acima, ou coloque isto em .vscode/mcp.json:

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

O VS Code pede que você faça login na primeira vez que o servidor iniciar.

Codex CLI

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

Um token estático em vez disso

Para CI, um contêiner ou um cliente sem suporte a OAuth, autentique com um cabeçalho. Crie uma conta em vidwords.com/register, verifique seu e-mail e depois crie uma chave na página API & MCP. O valor de uma chave é mostrado uma única vez, quando é criada.

Claude Code

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

Claude Desktop — `claude_desktop_config.json`

A mesma ponte mcp-remote de acima, com a chave em vez do login. Mantenha a chave em env: o Claude Desktop no Windows (e o Cursor, e o Codex CLI) não escapam espaços dentro de args, então Basic YOUR_API_TOKEN escrito lá se divide em dois — a solução alternativa do próprio README do 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" }
    }
  }
}

Mantenha isso fora do controle de versão, ou use ~/.cursor/mcp.json em vez disso — o cabeçalho contém uma credencial ativa.

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 envia Authorization: Bearer <value> e este servidor autentica com Basic.

Clientes sem suporte a cabeçalho personalizado, 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 direto deste repositório — o proxy não é publicado no npm, então um npx @vidwords/mcp puro não vai resolver.

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. A descoberta de recursos também é local; o upstream é contatado quando uma ferramenta, prompt ou recurso de UI é solicitado. O proxy também expõe os recursos de MCP Apps de análise e conta. Hosts compatíveis podem renderizar cartões interativos; o cartão de análise inclui Show full analysis. Leituras de recursos de UI e chamadas de ferramentas usam o mesmo upstream autenticado, e resultados estruturados passam inalterados.

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:${VIDWORDS_MCP_AUTH}"],
      "env": { "VIDWORDS_MCP_AUTH": "Basic YOUR_API_TOKEN" }
    }
  }
}

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

As treze ferramentas

Dois saldos pagam por elas: um Cloud Request busca a transcrição de um vídeo, e AI Units pagam pela leitura de frames e pela transcrição de áudio — uma análise de frame nova gasta um de cada tipo: 1 Cloud Request pela transcrição, mais AI Units por minuto de vídeo. Um vídeo que a conta já buscou está em sua Biblioteca, e lê-lo novamente é grátis — outro intervalo de tempo, outra página, uma busca após uma busca. Todo resultado medido informa o que ele charged.

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 um canal inteiro. Retorna os momentos correspondentes com timestamps, contexto citado e links profundos `youtube.com/watch?v=…&t=…s`. Opcional `from`/`to`.	1 Cloud Request por vídeo novo
`get_transcript`	Texto da transcrição para até 25 vídeos, ou o intervalo entre dois timecodes. `lang` escolhe uma faixa de legenda, `maxChars` pagina uma transcrição longa, `source: "audio"` transcreve a própria fala.	1 Cloud Request por vídeo novo
`search_library`	Busca de texto completo em todas as transcrições que a conta já salvou, com timestamps e links profundos.	Grátis
`list_library`	Os vídeos salvos da conta, do mais novo ao mais antigo, mais o ID da análise concluída mais recente.	Grátis
`list_analyses`	Análises AI Watch salvas com IDs, status e links de resultados; suporta paginação e filtro por vídeo.	Grátis
`list_languages`	As faixas de legenda que um vídeo tem, e quais são geradas automaticamente (a fala) versus enviadas (possivelmente traduções).	Grátis
`list_channel_videos`	Resolve um handle de canal, URL ou id `UC…` para seus uploads recentes.	1 Cloud Request · Starter e acima
`list_watchlists`	As listas de vigilância Radar da conta e quanto cada uma gravou.	Grátis
`watchlist_activity`	Uploads mais recentes que o Radar gravou para uma lista de vigilância.	Grátis
`account`	Plano e ambos os saldos, 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. `mode` é `quick`, `smart`, `deep` ou `auto`; Deep roda em qualquer plano com AI Units suficientes. `estimateOnly: true` retorna o preço em vez disso, sem iniciar nada.	1 Cloud Request, depois AI Units por minuto: Quick 2.8, Standard 4, Deep 30 · estimativa grátis
`get_analysis`	Lê uma análise concluída: visão geral, capítulos, pontos-chave, evidências com timestamp e etapas. Omita `analysisId` para abrir o resultado concluído mais recente. `waitSeconds` (até 25) mantém a chamada até que esteja pronto em vez de fazer polling.	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.	6 AI Units por pergunta

Verifique a Biblioteca primeiro

search_library e list_library leem o que a conta já tem, de graça. Um agente que busca na Biblioteca antes de buscar um vídeo novamente responde "o que aquela entrevista que eu assisti na semana passada disse sobre preços" sem gastar nada, e sem a ida e volta.

Prefira `search_transcript` em vez de `get_transcript`

Ambos custam um Cloud Request por vídeo novo, 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 inteiro: 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 nada — ele nunca amplia silenciosamente para o vídeo inteiro.

Pagine uma transcrição longa em vez de adivinhar intervalos

get_transcript aceita maxChars. Um resultado cortado diz truncated: true e carrega nextFrom, o segundo para continuar; passe-o de volta como from. O corte sempre cai entre legendas, e toda página após a primeira é uma releitura de um vídeo já na Biblioteca — grátis.

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

Qual idioma você obteve, e por quê

O idioma de uma faixa de legenda não é necessariamente o idioma falado. Uma faixa gerada automaticamente transcreve a fala; uma enviada pode ser uma tradução — alguns vídeos carregam uma dúzia de traduções da comunidade e nenhuma faixa no idioma realmente falado. Então toda transcrição diz por que ela é a faixa que é:

selectionReason: requested, spoken_language (corresponde à fala), caption_fallback (nenhuma faixa é conhecida por corresponder à fala — o inglês, se presente, foi escolhido para legibilidade), translated ou audio_transcription.
spokenLanguage: o idioma falado quando é conhecido, caso contrário null — não é um palpite.
lang pede uma faixa. Se o vídeo não tiver nenhuma nesse idioma, get_transcript responde language_unavailable com a availableLanguages que possui, e não cobra nada.
source: "audio" transcreve o que é dito em vez de ler as legendas — a maneira de obter as palavras originais quando toda legenda é uma tradução. É precificado como qualquer transcrição de áudio (3 Unidades de IA por minuto de vídeo, além da Solicitação de Nuvem) e passá-lo é o consentimento.

list_languages responde à mesma pergunta gratuitamente, a partir do que já está armazenado.

Uma chamada em 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 novo vídeo é cobrado na usual 1 Solicitação de Nuvem, 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 quadro que foi realmente gravado, uma afirmação falada tem que cair em um segmento real de transcrição. Qualquer coisa que falhe é 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 deste 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

Se você colou um token: Basic, não Bearer. O token é enviado como está; você não codifica em base64 um par user:pass. Clientes que fizeram login carregam suas próprias credenciais e isso não se aplica.
Verifique seu e-mail primeiro. Até que você clique no link de verificação, toda chamada retorna 403 com {"error":"email_unverified"} — a falha de primeira chamada mais comum em uma conta nova.
Os saldos são compartilhados com a API REST e o site. Uma Solicitação de Nuvem é uma nova transcrição; a análise de quadros gasta 1 Solicitação de Nuvem mais Unidades de IA, e a transcrição de áudio gasta Unidades de IA além da sua Solicitação de Nuvem. Uma execução recusada antes de começar não custa nada, e analyze_video com estimateOnly: true cotiza o preço gratuitamente.
Limite de taxa por minuto, por plano: Free 60, Starter 200, Pro 500, Team 1.000 solicitações. O servidor é sem estado, então um cliente reexecuta initialize antes de cada chamada e uma chamada de ferramenta é várias solicitações. 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 sobrevive a uma sessão de chamada de ferramenta. Use um token da 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.
Sem legendas, ou as erradas. Para um vídeo sem faixa de legenda, passe transcribeAudio: true para transcrevê-lo do áudio; para substituir legendas que existem (todas as traduções enviadas, por exemplo), passe source: "audio". Ambos são recursos pagos, precificados por minuto de vídeo, e nunca são executados sem serem solicitados.

Números completos: preços.

Prompts

O servidor também publica três prompts, que clientes como Claude mostram como ações prontas. Cada um diz ao modelo quais ferramentas usar e em que ordem, do mais barato primeiro.

Prompt	Argumentos	O que faz
`summarize_video`	`video`	Um resumo com carimbo de tempo de um vídeo, lido da maneira mais barata disponível.
`research_channel`	`channel`, `topic`	O que um canal disse sobre um tópico, com momentos citados.
`find_in_my_library`	`topic`	Pesquisa tudo o que já está salvo — grátis.

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, pesquisa em todo o canal, a tabela de custos e os códigos de erro que valem a pena agir, 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 recorrer a 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 uma issue 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 da VidWords.

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

VidWords YouTube

Documentação

Servidor MCP VidWords YouTube

Início rápido

Claude (claude.ai e Claude Desktop)

ChatGPT

Claude Desktop a partir de um arquivo de configuração

Claude Code

Cursor — um clique, ou .cursor/mcp.json

VS Code

Codex CLI

Um token estático em vez disso

Claude Code

Claude Desktop — claude_desktop_config.json

Cursor — .cursor/mcp.json

Codex CLI — ~/.codex/config.toml

Clientes sem suporte a cabeçalho personalizado, e Docker

As treze ferramentas

Verifique a Biblioteca primeiro

Prefira search_transcript em vez de get_transcript

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

Pagine uma transcrição longa em vez de adivinhar intervalos

Qual idioma você obteve, e por quê

Uma chamada em um canal

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

Autenticação, custo e limites

Prompts

Habilidade do agente

Documentação

Suporte

Licença

Cursor — um clique, ou `.cursor/mcp.json`

Claude Desktop — `claude_desktop_config.json`

Cursor — `.cursor/mcp.json`

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

Prefira `search_transcript` em vez de `get_transcript`