youtube-transcript-mcp

Servidor MCP local, em stdio, que expõe uma tool get_transcript(url, language?) para extrair a transcrição de um vídeo do YouTube — sem API key, sem depender de infraestrutura de terceiros.

Por que existe

Substitui o servidor remoto de terceiros listado em mcpmarket.com (ergut/youtube-transcript-mcp), cuja conexão via SSE falhava — o endpoint nunca envia o evento endpoint exigido pelo transporte SSE legado do MCP, só uma notificação solta (notifications/initialized), travando o cliente esperando. Este servidor roda inteiramente na sua máquina, sem cache de dados fora dela.

Contrato da tool

get_transcript(url: string, language?: string)
→ {
    videoId, title, channel, url,
    language, availableLanguages,
    transcript: { start: number, text: string }[]
    // start em segundos, precisão original do YouTube (não arredondado)
    // array, não dicionário por timestamp — evita reordenação de chave
    // inteira e colisão quando duas legendas caem no mesmo segundo
  }

Se language for pedido e não existir para aquele vídeo, retorna erro listando availableLanguages em vez de falhar silenciosamente. Aceita tanto o nome de exibição usado pelo YouTube (ex. "Portuguese", "English (auto-generated)") quanto o código ISO (ex. "pt", "en").

A tool só extrai e devolve texto/metadados — não grava nada em disco e não integra com nenhum sistema de memória. O que fazer com o resultado (salvar, processar, indexar) é responsabilidade de quem consome a tool.

Stack

Node + TypeScript, @modelcontextprotocol/sdk (transporte stdio) e youtubei.js para extração sem API key. Sem etapa de build — roda via npx tsx src/index.ts.

Risco conhecido: o endpoint interno de transcrição do YouTube já teve falhas HTTP 400 intermitentes reportadas na lib youtubei.js (LuanRT/YouTube.js#1102), e há discussão em aberto sobre exigência de PoToken para reduzir bloqueio por bot. Sem mitigação implementada por enquanto — se aparecer na prática, trate então (retry, PoToken, etc.).

Setup

git clone <url-deste-repo>
cd youtube-transcript-mcp
npm install

Registro no Claude Code (escopo local, só no projeto onde for usado):

claude mcp add --scope local youtube-transcript -- npx tsx /caminho/para/youtube-transcript-mcp/src/index.ts

Ajuste o caminho para onde você clonou o repositório.

Origem

Extraído de harness-engineering-scaffold — nasceu como parte de um projeto de harness engineering mais amplo, mas é uma ferramenta independente e genérica: qualquer projeto que precise extrair transcrições do YouTube pode usá-la sem depender do resto do scaffold.

Licença

MIT — ver LICENSE. Use, copie, modifique e redistribua livremente.