yt-dlp

🎬 yt-dlp-mcp

✨ Recursos

🚀 Instalação

Pré-requisitos

Instale o yt-dlp no seu sistema:

Primeiros Passos

Adicione a seguinte configuração ao seu cliente MCP:

{
  "mcpServers": {
    "yt-dlp": {
      "command": "npx",
      "args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"]
    }
  }
}

Configuração do Cliente MCP

claude mcp add yt-dlp npx @kevinwatt/yt-dlp-mcp@latest

{
  "mcpServers": {
    "yt-dlp": {
      "command": "npx",
      "args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"]
    }
  }
}

code --add-mcp '{"name":"yt-dlp","command":"npx","args":["-y","@kevinwatt/yt-dlp-mcp@latest"]}'

Instalação Manual

npm install -g @kevinwatt/yt-dlp-mcp

🛠️ Ferramentas Disponíveis

Todas as ferramentas são prefixadas com ytdlp_ para evitar conflitos de nomenclatura com outros servidores MCP.

🔍 Busca e Descoberta

📝 Legendas e Transcrições

🎥 Downloads de Vídeo e Áudio

📊 Metadados

💬 Comentários

💡 Exemplos de Uso

Buscar Vídeos

"Search for Python programming tutorials"
"Find the top 20 machine learning videos"
"Search for 'react hooks tutorial' and show results 10-20"
"Search for JavaScript courses in JSON format"

Obter Metadados

"Get metadata for https://youtube.com/watch?v=..."
"Show me the title, channel, and view count for this video"
"Extract just the duration and upload date"
"Give me a quick summary of this video's info"

Obter Comentários

"Get the top 20 comments for https://youtube.com/watch?v=..."
"Get comments as threaded JSON for this video"
"Extract comments as markdown_tree so the reply branches stay intact"
"Get newest comments with maxDepth 1 and maxRepliesPerThread 0"
"Summarize comments in threaded view"

Baixar Legendas e Transcrições

"List available subtitles for https://youtube.com/watch?v=..."
"Download English subtitles from this video"
"Get a clean transcript of this video in Spanish"
"Download Chinese (zh-Hant) transcript"

Baixar Conteúdo

"Download this video in 1080p: https://youtube.com/watch?v=..."
"Download audio from this YouTube video"
"Download this video from 1:30 to 2:45"
"Save this Facebook video to my Downloads"

📖 Documentação

• Referência da API - Documentação detalhada das ferramentas
• Configuração - Variáveis de ambiente e configurações
• Configuração de Cookies - Autenticação e acesso a vídeos privados
• Tratamento de Erros - Erros comuns e soluções
• Contribuição - Como contribuir

🔧 Configuração

Variáveis de Ambiente

# Downloads directory (default: ~/Downloads)
YTDLP_DOWNLOADS_DIR=/path/to/downloads

# Default resolution (default: 720p)
YTDLP_DEFAULT_RESOLUTION=1080p

# Default subtitle language (default: en)
YTDLP_DEFAULT_SUBTITLE_LANG=en

Consulte o Guia de Configuração para a lista completa.

Proxy e Arquivo de Configuração do yt-dlp

Todas as ferramentas leem seu arquivo de configuração do yt-dlp (~/.config/yt-dlp/config), então qualquer --proxy, --cookies ou outras opções definidas lá se aplicam automaticamente. Este é o único canal disponível para clientes MCP que não podem passar variáveis de ambiente para o processo do servidor.

Estas são alternativas — defina apenas a que você precisa:

Esquemas de proxy suportados: http, https, socks4, socks5, socks5h.

YTDLP_IGNORE_CONFIG=1 não é uma reversão direta para 0.9.x. As ferramentas de busca, metadados e comentários sempre leem o arquivo de configuração, então esta configuração impede que elas também o façam.

Configuração MCP com proxy:

{
  "mcpServers": {
    "yt-dlp": {
      "command": "npx",
      "args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"],
      "env": {
        "YTDLP_PROXY": "socks5://127.0.0.1:1080"
      }
    }
  }
}

Se o seu cliente MCP não puder passar variáveis de ambiente para o servidor, coloque as opções em ~/.config/yt-dlp/config — toda ferramenta lê esse arquivo:

--proxy socks5://127.0.0.1:1080
--cookies /path/to/cookies.txt

Nota: Seu arquivo de configuração também se aplica a downloads. Opções que alteram o formato de saída (-x, --remux-video, --recode-video) alteram o que as ferramentas de download produzem; as ferramentas relatam o arquivo que o yt-dlp realmente gravou, então o nome relatado permanece correto. Opções de local de saída (-o, -P) não têm efeito, porque as ferramentas sempre passam um --output absoluto na linha de comando, que tem precedência.

Nota: Arquivos de configuração do yt-dlp podem conter opções que executam comandos (--exec, --postprocessor-args, --ffmpeg-location). Elas agora também são executadas em invocações de ferramentas, incluindo aquelas acionadas por um assistente de IA. Defina YTDLP_IGNORE_CONFIG=1 se preferir que o servidor ignore completamente seu arquivo de configuração.

Configuração de Cookies

Para acessar vídeos privados, conteúdo com restrição de idade ou evitar limites de taxa, configure cookies:

⚠️ Importante: A autenticação por cookies requer um runtime JavaScript (deno) instalado. Ao usar cookies, o YouTube usa endpoints de API autenticados que exigem a resolução de desafios JavaScript. Sem o deno, os downloads falharão com o erro "n challenge solving failed".

Instale o deno: https://docs.deno.com/runtime/getting_started/installation/

# Extract cookies from browser (recommended)
YTDLP_COOKIES_FROM_BROWSER=chrome

# Or use a cookie file
YTDLP_COOKIES_FILE=/path/to/cookies.txt

Configuração MCP com cookies:

{
  "mcpServers": {
    "yt-dlp": {
      "command": "npx",
      "args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"],
      "env": {
        "YTDLP_COOKIES_FROM_BROWSER": "chrome"
      }
    }
  }
}

Navegadores suportados: brave, chrome, chromium, edge, firefox, opera, safari, vivaldi, whale

Consulte o Guia de Configuração de Cookies para instruções detalhadas de configuração.

🏗️ Arquitetura

Construído Com

• yt-dlp - Mecanismo de extração de vídeo
• MCP SDK - Protocolo de Contexto de Modelo
• Zod - Validação de esquema com foco em TypeScript
• TypeScript - Segurança de tipos e experiência do desenvolvedor

Principais Recursos

• ✅ Type-Safe: TypeScript completo com modo estrito
• ✅ Entradas Validadas: Esquemas Zod para validação em tempo de execução
• ✅ Limites de Caracteres: Truncamento automático para evitar estouro de contexto
• ✅ Anotações de Ferramentas: Dicas readOnly, destructive, idempotent
• ✅ Orientação de Erros: Mensagens de erro acionáveis para LLMs
• ✅ Design Modular: Separação clara de responsabilidades

📊 Formatos de Resposta

Formato JSON

Perfeito para processamento programático:

{
  "total": 50,
  "count": 10,
  "offset": 0,
  "videos": [...],
  "has_more": true,
  "next_offset": 10
}

Formato Markdown

Exibição legível para humanos:

Found 50 videos (showing 10):

1. **Video Title**
   📺 Channel: Creator Name
   ⏱️  Duration: 10:30
   🔗 URL: https://...

Árvore de Comentários em Markdown

Útil para análise por LLM quando o contexto de resposta importa:

# AI-Ready Comment Threads

source_title: "Sample Video"
comments_detected: 20
root_threads: 6
reply_comments: 14

## Threads

### Thread 1

- comment_id: "abc123"
  parent_id: "root"
  depth: 0
  reply_count: 2
  text:
    | Root comment text
  - comment_id: "reply456"
    parent_id: "abc123"
    depth: 1
    reply_count: 0
    text:
      | Reply text

Limites de Comentários

A extração de comentários do YouTube suporta a tupla completa do extrator:

youtube:comment_sort=<sort>;max_comments=<total>,<parents>,<replies>,<repliesPerThread>,<depth>

Exemplos:

• Comportamento padrão: maxComments=20 produz max_comments=20,20,20,20,2
• Comentários apenas raiz: maxDepth=1, maxRepliesPerThread=0
• Ramificação limitada: maxReplies=40, maxRepliesPerThread=5, maxDepth=2

🔒 Privacidade e Segurança

• Sem Rastreamento: Downloads diretos, sem análises
• Validação de Entrada: Esquemas Zod previnem injeção
• Validação de URL: Verificação estrita do formato de URL
• Limites de Caracteres: Previne ataques de estouro de contexto
• Somente Leitura por Padrão: A maioria das ferramentas não modifica o estado do sistema

🤝 Contribuindo

Contribuições são bem-vindas! Consulte nosso Guia de Contribuição.

1. Faça um fork do repositório
2. Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
3. Faça commit das suas alterações (git commit -m 'Add amazing feature')
4. Envie para o branch (git push origin feature/amazing-feature)
5. Abra um Pull Request

📝 Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

🙏 Agradecimentos

• yt-dlp - A incrível ferramenta de extração de vídeo
• Anthropic - Pelo Protocolo de Contexto de Modelo
• Dive - Plataforma de IA compatível com MCP

📚 Projetos Relacionados

• MCP Servers - Implementações oficiais de servidores MCP
• yt-dlp - Downloader de vídeo por linha de comando
• Dive Desktop - Plataforma de agente de IA