Skip to main content
Glama
README.md
# mcp-legendas-youtube

Servidor MCP local que entrega ao Claude a **legenda de um vídeo do YouTube** como texto, e guarda uma cópia em Markdown.

Quem busca a legenda é o [yt-dlp](https://github.com/yt-dlp/yt-dlp), um programa público e mantido. O MCP escolhe a melhor legenda, organiza o texto e explica os erros.

## O que ele faz

- Uma ferramenta só: **`get_transcript`**, com dois campos:
  - `url`: o link do vídeo (`youtube.com/watch?v=`, `youtu.be/`, `/shorts/`, `/embed/`) ou só o ID de 11 caracteres;
  - `idioma` (opcional): **um** código, como `pt`, `pt-BR` ou `en`. Vazio = idioma original do vídeo.
- **Prefere a legenda revisada por pessoas** (manual). Sem ela, usa a automática do idioma original do vídeo e **avisa** que é automática.
- Pedindo outro idioma: manual nesse idioma; senão, a automática original nele; senão, a tradução automática do YouTube. Se a tradução falhar, entrega a do idioma original, com aviso.
- A resposta traz título, canal, link, data de publicação, duração e o tipo de legenda, e o texto corrido com **marcas de tempo** em 10%, 25%, 50%, 75% e 90% do vídeo.
- **Salva um arquivo `.md`** com a mesma legenda (detalhes em [Onde ficam os arquivos](#onde-ficam-os-arquivos)).

## O que ele não faz

- **Não usa conta do YouTube**: sem login e sem cookies. Por isso não pega vídeo privado, só para membros ou com restrição de idade. Nesses casos, ele explica o motivo e para.
- **Não contorna bloqueios** (verificação anti-robô, excesso de pedidos, proteção de cópia).
- **Não cria legenda**: só traz a que já existe no YouTube. Vídeo sem legenda continua sem legenda.
- Não baixa vídeo nem áudio.

## Requisitos

- **Node.js 18 ou mais novo** (`node --version`).
- **Claude Code**.
- Windows, macOS ou Linux (no Linux e no macOS, processador x64 ou arm64).
- Python **não** é necessário: o yt-dlp vem como um executável pronto.
- **Git**, para baixar o projeto (ou uma cópia da pasta, veja abaixo).

## Instalação

Antes de começar, decida três coisas:

1. **Em qual pasta fixa** o projeto vai ficar. O registro no Claude aponta para ela.
2. **O escopo do registro**: `user` (recomendado, o MCP funciona em qualquer pasta onde você abrir o Claude) ou `local` (só em uma pasta; nesse caso, qual).
3. **Onde salvar as legendas**: na pasta `legendas/` de onde o Claude for aberto (o padrão), ou numa pasta fixa (`LEGENDAS_DIR`).

### Instalando com a ajuda do Claude

Se você passar o link deste repositório para o Claude (ou outro assistente) e pedir que ele instale, as instruções abaixo são para ele.

> **Para o assistente que vai instalar:** antes de executar qualquer comando, **pergunte ao usuário** as três decisões acima (pasta, escopo e pasta das legendas). Não escolha por ele, nem use o padrão do `claude mcp add` sem perguntar.
> Depois, siga os passos 1 a 3 desta seção, usando o comando de registro do escopo escolhido (o instalador mostra os dois).
> Regras: não coloque o yt-dlp no PATH; não use cookies, login nem conta do YouTube; não contorne bloqueios. Se o checksum não conferir, pare e avise.
> No fim, avise que é preciso **abrir uma conversa nova** no Claude para o MCP aparecer.

### 1. Baixe o projeto

O repositório é público: o `git clone` não pede login.

```bash
git clone https://github.com/joaomelchiors/mcp-legendas-youtube.git
```

```bash
cd mcp-legendas-youtube
```

Rode o `git clone` dentro da pasta fixa que você escolheu. Se mover a pasta depois, remova o registro e registre de novo.

**Sem GitHub:** copie a pasta do projeto **sem** `node_modules/`, `dist/`, `coverage/`, `canario/` e `legendas/`, e siga daqui.

### 2. Instale

Na pasta do projeto, rode:

```bash
npm run instalar
```

Ele faz, em ordem:

1. `npm install` e o build;
2. **confere as dependências que o MCP executa** (`npm audit --omit=dev`) e **para** se houver uma vulnerabilidade alta ou crítica. Hoje o resultado é `found 0 vulnerabilities`;
3. cria a pasta privada do MCP, `~/.mcp-legendas-youtube/` (no Windows, `%USERPROFILE%\.mcp-legendas-youtube\`);
4. baixa do **GitHub oficial do yt-dlp** a versão fixa do projeto e a lista de checksums dessa versão;
5. **confere o checksum** e só então grava o yt-dlp. Se não conferir, descarta o arquivo e não instala nada;
6. roda o yt-dlp com `--version` para confirmar;
7. mostra os **dois comandos de registro** (`user` e `local`), já com o caminho completo.

O yt-dlp fica **só nessa pasta privada**. Ele não vai para o PATH nem fica disponível para outros programas.

Se o yt-dlp certo já estiver na pasta, nada é baixado de novo.

**Sobre os avisos do `npm audit`:** se você rodar `npm install` ou `npm audit` por conta própria, o npm mostra avisos (hoje 19: 3 baixos e 16 moderados, nenhum alto ou crítico). Todos estão nas **ferramentas de teste** (Jest), que só rodam no computador de quem desenvolve, com arquivos do próprio projeto. **Nenhum está no que o MCP executa.** A "correção" que o npm oferece seria voltar o Jest para uma versão muito antiga, então eles ficam aceitos até sair uma versão nova do Jest. Para conferir só o que o MCP executa, a qualquer momento:

```bash
npm run auditoria
```

### 3. Registre no Claude Code

O instalador mostra **dois comandos**. Copie **um só**, o do escopo que você escolheu:

| Escopo | Onde o MCP aparece | Onde rodar o comando |
| --- | --- | --- |
| `user` (recomendado) | em qualquer pasta onde você abrir o Claude | em qualquer lugar |
| `local` | só em uma pasta | **dentro** dessa pasta |

```bash
claude mcp add --scope user mcp-legendas-youtube -- node "<pasta do projeto>/dist/index.js"
```

```bash
claude mcp add --scope local mcp-legendas-youtube -- node "<pasta do projeto>/dist/index.js"
```

Se não disser o escopo, o `claude mcp add` usa `local`. Depois de registrar, **abra uma conversa nova** no Claude.

**Variáveis opcionais** entram com `-e`, **depois do nome e logo antes do `--`**:

- `LEGENDAS_DIR`: pasta fixa para os arquivos `.md` (veja [Onde ficam os arquivos](#onde-ficam-os-arquivos));
- `YT_DLP_PATH`: um yt-dlp em outro lugar, em vez do da pasta privada.

```bash
claude mcp add --scope user mcp-legendas-youtube -e LEGENDAS_DIR="<pasta>" -- node "<pasta do projeto>/dist/index.js"
```

Para mudar o registro depois, remova e registre de novo (use o escopo com que registrou):

```bash
claude mcp remove --scope user mcp-legendas-youtube
```

Para ver se já existe um registro, e com qual escopo:

```bash
claude mcp get mcp-legendas-youtube
```

## Como usar

Peça ao Claude em linguagem normal. Exemplos:

- "Pegue a legenda deste vídeo: https://youtu.be/iG9CE55wbtY"
- "Quero a legenda em português de https://www.youtube.com/watch?v=iG9CE55wbtY"
- "Resuma este vídeo a partir da legenda: https://youtu.be/..."

O Claude converte o nome do idioma ("português") no código (`pt`).

Se não houver legenda no idioma pedido, a resposta lista as legendas que existem, para você escolher.

### Onde ficam os arquivos

- Cada legenda vira um arquivo em **`legendas/`, dentro da pasta onde o Claude foi aberto**.
- Nome do arquivo: `data_título_idioma_ID.md`, por exemplo `2007-01-07_do-schools-kill-creativity-sir-ken-robinson-ted_pt-BR_iG9CE55wbtY.md`.
- Pedir o mesmo vídeo no mesmo idioma de novo **substitui** o arquivo (não duplica).
- Para guardar sempre na mesma pasta (por exemplo, um cofre do Obsidian), registre com a variável **`LEGENDAS_DIR`** (exemplo em [Registre no Claude Code](#3-registre-no-claude-code)).
- A primeira linha da resposta diz onde o arquivo foi salvo. Se não deu para salvar, a legenda vem do mesmo jeito, com um aviso no lugar.

### Conteúdo de terceiros

Título, canal e legenda são escritos por quem publicou o vídeo. A resposta os coloca entre marcadores, com um aviso de que são conteúdo e não instruções. Mesmo assim, desconfie de uma legenda que "peça" alguma coisa ao Claude.

## Manutenção

O YouTube muda de tempos em tempos, e aí o yt-dlp precisa de atualização.

- **Canário**: um teste rápido e real, com um vídeo do TED, que diz se o YouTube ou o yt-dlp mudou. Leva uns 20 segundos e faz só 2 pedidos ao YouTube.

  ```bash
  npm run canario
  ```

  Termina com `Resultado: OK` ou `Resultado: FALHOU na etapa N`, e guarda um resumo em `canario/ultima-execucao.json`.

- **Parou de funcionar?** Siga o guia [docs/o-youtube-mudou.md](docs/o-youtube-mudou.md): canário, qual etapa falhou, onde fica o log do MCP, como atualizar o yt-dlp e o que significa cada erro.

- **Atualizar o yt-dlp**: troque a versão no `package.json`, em `"config": { "ytDlpVersion": "..." }`, pela nova (veja em `https://github.com/yt-dlp/yt-dlp/releases`). Feche o Claude (o MCP usa o arquivo), rode `npm run instalar` e depois `npm run canario`.

- **Atualizar o projeto** (por exemplo, nos outros computadores, depois que a versão nova foi enviada ao repositório): feche o Claude e rode, na pasta do projeto:

  ```bash
  git pull
  ```

  ```bash
  npm run instalar
  ```

## Limites

- Só legendas que **já existem** no YouTube.
- Sem login: **sem** vídeo privado, de membros ou com restrição de idade.
- Live agendada ou em andamento: a legenda só existe depois que a transmissão termina.
- **Excesso de pedidos**: o YouTube pode bloquear por um tempo (erro 429). A saída é esperar, não insistir.
- **Depende do yt-dlp**: quando o YouTube muda, o MCP volta a funcionar quando sai uma versão nova do yt-dlp.
- Cada execução do yt-dlp tem limite de 90 segundos.

## Uso pessoal e termos do YouTube

Este projeto é para **uso pessoal e local**: obter a legenda de vídeos públicos para estudo e anotação, sem redistribuir o conteúdo e sem oferecer como serviço.

Os **termos de uso do YouTube** continuam valendo para quem usa. A licença deste projeto cobre só o código: ela não autoriza baixar conteúdo de ninguém. Use com responsabilidade. Isto não é orientação jurídica.

## Segurança

Revisão completa, item por item, em [docs/seguranca.md](docs/seguranca.md). Em resumo:

- o MCP só executa o yt-dlp, sem shell e com argumentos montados por ele;
- só grava em `legendas/` (ou `LEGENDAS_DIR`), em `canario/` e, na instalação, na pasta privada do yt-dlp;
- o instalador só baixa do GitHub oficial do yt-dlp e confere o checksum antes de gravar.

## Desenvolvimento

```bash
npm test
```

```bash
npm run test:cobertura
```

```bash
npm run tipos:testes
```

```bash
npm run build
```

```bash
npm run e2e
```

- `npm test`: compila e roda todos os testes (Jest), sem internet e sem o yt-dlp real. Inclui o teste ponta a ponta sem rede ([test/e2e/stdio.e2e.test.ts](test/e2e/stdio.e2e.test.ts)): sobe o servidor de verdade (`node dist/index.js`) e conversa com ele pelo stdio, como o Claude faz.
- `npm run test:cobertura`: os testes com o relatório de cobertura.
- `npm run tipos:testes`: confere os tipos dos testes.
- `npm run build`: compila para `dist/`.
- `npm run auditoria`: `npm audit` só do que o MCP executa (sem as ferramentas de teste).
- `npm run e2e`: o teste ponta a ponta **com rede** ([test/e2e/youtube.rede.test.ts](test/e2e/youtube.rede.test.ts)): servidor, yt-dlp e YouTube reais. Pede a legenda `pt-BR` do vídeo do TED e confere a resposta e o `.md` salvo numa pasta temporária. Precisa do yt-dlp instalado (`npm run instalar`) e fica fora do `npm test`.

**Diagrama da arquitetura:** [docs/arquitetura.excalidraw](docs/arquitetura.excalidraw), com as camadas, quem depende de quem, o fluxo de uma chamada arquivo por arquivo e a inversão de dependência. Abra em [excalidraw.com](https://excalidraw.com) (menu, Abrir) ou no plugin Excalidraw do Obsidian. Seta contínua é "depende de", seta tracejada com triângulo vazado é "implementa" (inversão de dependência) e seta pontilhada é dado em tempo de execução.

Organização do código (`src/`):

- `domain/`: as regras (que legenda escolher, o que vai na legenda, os erros), sem depender do yt-dlp;
- `infra/engine/`: o yt-dlp (argumentos, leitura das saídas, legenda VTT);
- `infra/mcp/`: a ferramenta, o servidor MCP e os textos da resposta;
- `infra/storage/`: o arquivo `.md` salvo;
- `infra/canary/` e `infra/install/`: o canário e o instalador;
- `index.ts`, `canary.ts` e `install.ts`: os pontos de entrada.

## Licença

[MIT](LICENSE), © 2026 João Marcos Melchiors.

O yt-dlp tem a própria licença (Unlicense). Ele é baixado do projeto oficial na instalação e não vem junto com este código.

TDQS

A4.1/5.0

Scored across 1 tool

Disambiguation5/5

There is only one tool, so there is no possibility of selecting the wrong one. Its purpose (fetching a YouTube video's transcript as text) is stated explicitly and unambiguously.

Naming Consistency5/5

The single name follows a clean verb_noun snake_case pattern (get_transcript) and matches the domain vocabulary used in the description. No conflicting conventions exist.

Tool Count3/5

One tool is functional but thin for a server dedicated to YouTube captions: it cannot express language choice, format, or availability checking. The surface feels minimal rather than well-scoped.

Completeness3/5

The core retrieval operation is covered, but obvious adjacent operations are missing: listing available caption languages/tracks, requesting a specific language, or getting timestamps/segments instead of plain text. Agents facing a multilingual video or a transcript-less case have no fallback.