transcriptor-mcp

Um servidor MCP (stdio + HTTP/SSE) que busca transcrições/legendas de vídeos via yt-dlp, com paginação para respostas grandes. Suporta YouTube, Twitter/X, Instagram, TikTok, Twitch, Vimeo, Facebook, Bilibili, VK, Dailymotion. Fallback Whisper — transcreve áudio quando legendas não estão disponíveis (local ou API OpenAI). Funciona com Cursor e outros hosts MCP.

GitHub

Documentação

🎬 Agora seu assistente de IA pode assistir vídeos!

Conecte um servidor. Depois pergunte ao Claude, ChatGPT ou outros sobre um vídeo: a transcrição, os capítulos, os metadados ou um único quadro. Funciona com 11 plataformas, não apenas YouTube.

Conectar · O que perguntar · Widgets · Plataformas · Self-host

⚡ Conecte em 30 segundos

O endpoint hospedado é:

https://transcriptor.gateway.mcpal.io/mcp

🖱️ Um clique

⌨️ Um comando, para Claude Code

claude mcp add --transport http transcriptor https://transcriptor.gateway.mcpal.io/mcp

Depois execute /mcp e aprove o login no navegador. Após isso, claude mcp list mostra ✔ Connected.

🧭 Sem terminal

Cliente	O que fazer
Claude (web e desktop)	Abra Configurações → Personalizar → Conectores. Selecione Adicionar → Adicionar conector personalizado, cole `https://transcriptor.gateway.mcpal.io/mcp` e selecione Adicionar.
ChatGPT	Abra Transcriptor no diretório de plugins do ChatGPT e selecione Instalar plugin; faça login quando solicitado. Ou no ChatGPT abra Plugins, pesquise Transcriptor, selecione Instalar plugin. Depois mencione `@Transcriptor` em um chat.
Codex	Mesmo diretório, uma instalação: ChatGPT e Codex compartilham. Em uma tarefa do Codex abra Fontes → Usar plugins → Transcriptor; na CLI, `/plugins`.

Nota: uma nova listagem no diretório pode levar até 6 horas para aparecer no Codex (Plugins no ChatGPT e Codex).

🧩 Qualquer outro cliente MCP

Se seu cliente não estiver na lista acima, adicione o servidor com esta configuração:

{
  "mcpServers": {
    "transcriptor": {
      "url": "https://transcriptor.gateway.mcpal.io/mcp"
    }
  }
}

Se quiser executar o servidor você mesmo, leia Self-host. As ferramentas são as mesmas e você não precisa de conta.

🧰 O que você pode perguntar

Peça isto	Ferramenta
"Resuma este vídeo para mim"	`get_transcript`
"Me dê as legendas como arquivo SRT"	`get_raw_subtitles`
"Existe uma faixa em alemão para este vídeo?"	`get_available_subtitles`
"Quem publicou e quantas visualizações tem?"	`get_video_info`
"Vá para a parte sobre preços"	`get_video_chapters`
"Me mostre a tela em 4:12"	`get_video_frame`
"Obtenha transcrições dos primeiros 5 vídeos desta playlist"	`get_playlist_transcripts`
"Encontre vídeos recentes sobre X"	`search_videos` (YouTube)

Transcrições longas vêm em partes. Cada resposta fornece um cursor para a próxima parte, então nenhum texto é perdido.

Referência completa das ferramentas (entrada e resposta estruturada)

Cada ferramenta que aceita um vídeo aceita url. Isso é um link de uma plataforma suportada ou um ID simples do YouTube. Cada ferramenta retorna content (texto para o chat) e structuredContent (JSON tipado para seu código).

`get_transcript`

Texto simples e limpo, sem timestamps, HTML ou nomes de falantes. A ferramenta encontra o tipo e o idioma para você.

Resposta: videoId, url (a página do vídeo, como o servidor a resolveu), type, lang, text, is_truncated, total_length, start_offset, end_offset. Quando há mais texto disponível, a resposta também tem next_cursor.

`get_raw_subtitles`

Conteúdo bruto em SRT ou VTT, em partes.

Entrada:

type — official ou auto
lang — um código de idioma
response_limit — padrão 50000, mínimo 1000, máximo 200000
next_cursor — o cursor da resposta anterior

Resposta: os campos de get_transcript, mais format (srt ou vtt) e content.

`get_available_subtitles`

Resposta: official e auto. Cada campo é uma lista ordenada de códigos de idioma. Use esta ferramenta primeiro, depois forneça type e lang às ferramentas acima.

`get_video_info`

Metadados estendidos do yt-dlp:

identidade — videoId, title, description, webpageUrl
autor — uploader, uploaderId, channel, channelId, channelUrl
números — duration, uploadDate, viewCount, likeCount, commentCount
classificação — tags, categories, liveStatus, isLive, wasLive, availability
imagens — thumbnail e thumbnails

`get_video_chapters`

Resposta: chapters. Cada item tem startTime, endTime e title. Quando o vídeo não tem capítulos, a lista fica vazia.

`get_video_frame`

Entrada:

timecode — "MM:SS" ou "HH:MM:SS.mmm"
seconds — uma alternativa a timecode. Forneça um dos dois, não ambos
format — jpeg (padrão) ou png
width — padrão 1280, máximo 1920, nunca maior que a fonte
quality — 2 a 31, apenas para jpeg

Resposta: um bloco de imagem, mais url, timestampSeconds, timestamp, mimeType, sizeBytes e width. Esta ferramenta precisa de ffmpeg. A imagem Docker o inclui.

`get_playlist_transcripts`

Entrada:

url — uma URL de playlist, ou uma URL de watch com list=
type, lang, format — os mesmos que get_raw_subtitles
playlistItems — um valor -I do yt-dlp, como 1:5, 1,3,7 ou -1
maxItems — o número máximo de vídeos

Resposta: results. Cada item tem videoId e text.

`search_videos`

Entrada:

query — o texto da busca
limit — padrão 10, máximo 50
offset — o número de resultados a pular
uploadDateFilter — hour, today, week, month ou year
response_format — json (padrão) ou markdown

Resposta: results. Cada item tem videoId, title, url, duration, uploader, viewCount e thumbnail.

📺 Widgets

Quatro ferramentas têm uma interface interativa: get_transcript, get_video_info, get_video_frame e search_videos. Clientes que suportam MCP Apps e o SDK de Apps do ChatGPT mostram essa interface no chat. Outros clientes recebem os mesmos dados como texto e JSON.

_{search_videos · "model context protocol MCP server production"}	_{get_video_frame · um slide de arquitetura em 3:30}
_{get_transcript · um explicador de MCP de 3 minutos, legendas oficiais}	_{get_video_info · canal, visualizações, curtidas e 169 idiomas de legenda}

🌍 Plataformas

YouTube · Twitter/X · Instagram · TikTok · Twitch · Vimeo · Facebook · Bilibili · VK · Dailymotion · Reddit

Cada ferramenta que aceita um vídeo aceita um link dessas 11 plataformas. A ferramenta search_videos funciona apenas com YouTube, por meio do yt-dlp ytsearch.

O servidor não baixa arquivos de vídeo ou áudio para você. Ele retorna texto, metadados e quadros individuais.

🐳 Self-host

As ferramentas são as mesmas do endpoint hospedado. Você não precisa de conta.

Execute o servidor com Docker. A imagem serve Streamable HTTP na porta 4200:

docker run --rm -p 4200:4200 artsamsonov/transcriptor-mcp:latest

Depois aponte seu cliente para http://localhost:4200/mcp.

Para stdio, dê à imagem um comando explícito:

docker run --rm -i artsamsonov/transcriptor-mcp:latest npm run start:mcp

{
  "mcpServers": {
    "transcriptor": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "artsamsonov/transcriptor-mcp:latest", "npm", "run", "start:mcp"]
    }
  }
}

O servidor inicia sem variáveis de ambiente. Cada variável abaixo é opcional.

Variável	Padrão	Função
`MCP_PORT` e `MCP_HOST`	`4200` e `0.0.0.0`	O listener HTTP
`COOKIES_FILE_PATH`	—	Um arquivo de cookies Netscape para vídeos que precisam de conta. Veja cookies.example.txt
`WHISPER_MODE`	`off`	Defina `local` ou `api` para transcrever o áudio quando um vídeo não tem legendas. Depois defina `WHISPER_BASE_URL` ou `WHISPER_API_KEY`. `WHISPER_MAX_DURATION_SECONDS` pula vídeos mais longos e transmissões ao vivo; um vídeo cuja duração a plataforma não informa é medido com `ffprobe` após o download do áudio
`CACHE_MODE`	`off`	Defina `redis` e `CACHE_REDIS_URL` para armazenar legendas e metadados em cache
`YT_DLP_MAX_CONCURRENCY`	`4`	Quantos processos yt-dlp/ffmpeg podem rodar ao mesmo tempo. `YT_DLP_MAX_QUEUE` (`8`) é quantas chamadas podem esperar; além disso, uma chamada é recusada imediatamente com "servidor ocupado". Uma chamada atinge pico de ~40 MiB, então o limite controla a limitação da plataforma e a latência, não a memória
`CANARY_INTERVAL_MS`	`900000`	Com que frequência o servidor HTTP busca uma transcrição para provar que o caminho ainda funciona. `0` desativa; `CANARY_URL` escolhe o vídeo
`YT_DLP_*`	—	Timeouts, proxy e runtimes JS. Veja .env.example

A mesma porta serve GET /health e GET /metrics. As métricas estão no formato Prometheus e incluem os contadores mcp_*.

Transporte, API REST e desenvolvimento

Transporte. O servidor aceita apenas POST /mcp. GET e DELETE retornam 405. O servidor não tem estado e não envia Mcp-Session-Id.

O processo Node não verifica tokens de portador. Coloque um proxy reverso ou um gateway na frente para autenticação e TLS. O endpoint hospedado funciona assim.

API REST. Uma segunda imagem fornece a mesma extração por HTTP simples:

docker run --rm -p 3000:3000 artsamsonov/transcriptor-mcp-api:latest

A interface Swagger está em http://localhost:3000/docs. Para uma pilha completa com a API e o servidor MCP, leia docker-compose.example.yml.

Desenvolvimento.

npm ci
npm run build
npm run dev:mcp        # stdio, hot reload
npm run dev:mcp:http   # Streamable HTTP, hot reload
npm test

Você precisa de Node.js 22 ou posterior (20 ainda funciona, mas atingiu o fim da vida em abril de 2026) e yt-dlp no seu PATH. A captura de quadros precisa de ffmpeg, e WHISPER_MAX_DURATION_SECONDS precisa de ffprobe (ambos vêm no mesmo pacote e na imagem Docker). Outros scripts: lint, type-check, format, test:coverage, test:e2e:api e test:e2e:mcp.

Versões. A versão vem de package.json em tempo de execução, por meio de src/version.ts. Altere esta versão, mova as entradas [Unreleased] do changelog para a nova versão e envie uma tag v*. A CI compila ambas as imagens e publica a entrada do MCP Registry a partir de server.json. Layout. src/mcp.ts (entrada stdio), src/mcp-http.ts (HTTP Streamable), src/mcp-core.ts (ferramentas, prompts, widgets), src/youtube.ts (yt-dlp), src/whisper.ts, src/cache.ts, src/index.ts (API REST), load/ (k6) e src/e2e/ (testes de fumaça Docker).

🤝 Contribuindo

Pull requests são bem-vindos. Faça um fork do repositório, crie uma branch e garanta que npm test e npm run lint passem. Em seguida, abra um pull request.

⚖️ Legal

O endpoint hospedado em transcriptor.gateway.mcpal.io é regido pelos Termos de Serviço e pela Política de Privacidade.

Um servidor que você mesmo hospeda não é coberto por esses documentos. Ele é regido apenas pela Licença MIT.

📄 Licença

💬 Suporte

Issues · Perfil no GitHub · LinkedIn