Skip to main content
Glama
gomesmr

youtube-transcript-mcp

by gomesmr
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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.

Related MCP server: youtube-mcp

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.

Available Tools

1 tool
get_transcriptC

Extrai a transcrição de um vídeo do YouTube a partir da URL (ou ID do vídeo).

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesURL do vídeo do YouTube (watch, youtu.be, shorts, embed) ou o ID do vídeo diretamente
languageNoNome de exibição (ex: "Portuguese", "English (auto-generated)") ou código ISO (ex: "pt", "en") do idioma desejado. Se omitido, usa o idioma padrão do vídeo.

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden. It only says 'extracts transcript' without disclosing behavioral traits like rate limits, authentication, or behavior when transcript is unavailable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with key information. No wasted words, though it could benefit from slightly more detail without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, but description does not explain return values (e.g., plain text transcript, error cases). Also lacks behavioral context. Incomplete for a tool with no annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds minimal extra meaning beyond the schema (e.g., 'from URL or video ID' is already in url description). No further detail on language format.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool extracts a YouTube transcript from a URL or video ID (verb+resource). However, there are no sibling tools to differentiate from, so it doesn't need further distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool vs. alternatives, nor does it mention prerequisites or limitations. It only states what it does, not when to invoke it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.1.0
    • First observedget_transcript
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 1 tool

Disambiguation5/5

There is only one tool, so there is no possibility of confusion or overlap between tools. The single tool has a clearly distinct purpose.

Naming Consistency5/5

With only one tool named 'get_transcript', naming is trivially consistent. It follows a verb_noun pattern (get_transcript), which is clear and predictable.

Tool Count3/5

The server has only one tool, which is at the lower end of the appropriate range. While it serves a focused purpose, a single tool feels thin and may limit usefulness.

Completeness5/5

The tool fully covers its intended purpose of extracting transcripts from YouTube videos via URL or ID. No obvious gaps exist for the given domain.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers