# 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`](https://github.com/modelcontextprotocol/sdk)
(transporte stdio) e [`youtubei.js`](https://github.com/LuanRT/YouTube.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](https://github.com/LuanRT/YouTube.js/issues/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

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

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

```bash
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](https://github.com/gomesmr/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](LICENSE). Use, copie, modifique e redistribua livremente.