YouTube Data MCP

Servidor MCP de alta eficiência para YouTube, fornecendo dados estruturados e otimizados em tokens para LLMs.

Documentação

Servidor YouTube Data MCP (@kirbah/mcp-youtube)

Um servidor YouTube Data MCP de nível de produção, projetado especificamente para agentes de IA.

Diferente de wrappers de API comuns que inundam seu LLM com dados redundantes, este servidor remove o excesso de peso das respostas pesadas do YouTube. Ele foi projetado para economizar uma quantidade massiva de tokens do contexto, proteger suas cotas diárias de API por meio de cache e funcionar de forma confiável sem quebrar seus fluxos de trabalho.

Por que escolher este servidor?

A maioria dos servidores MCP são projetos de fim de semana. O @kirbah/mcp-youtube foi construído para fluxos de trabalho agênticos confiáveis, diários e econômicos.

🎯 Quer feedback sobre o seu próprio canal, não apenas dados brutos? Confira o CreatorLens - uma Skill do Claude construída sobre este MCP que diagnostica problemas comuns de crescimento (ganchos fracos, miniaturas ruins, vídeos estagnados) usando uma estrutura de estrategista real, não apenas números.

📉 1. Economize até 87% em Tokens (e Janela de Contexto)

A API bruta do YouTube retorna payloads JSON enormes, repletos de eTags aninhados, miniaturas redundantes e dados de localização que os LLMs não precisam. Este servidor estrutura os dados para dar ao seu LLM exatamente o que ele precisa para raciocinar, e nada mais.

%%{init: { "theme": "base", "themeVariables": { "xyChart": { "plotColorPalette": "#ef4444, #22c55e" } } } }%%
xychart-beta
    title "Token Consumption (Lower is Better)"
    x-axis ["getVideoDetails", "searchVideos", "getChannelStats"]
    y-axis "Context Tokens" 0 --> 1200
    bar "Raw YouTube API" [854, 1115, 673]
    bar "MCP-YouTube (Optimized)" [209, 402, 86]

Método da API	Tokens brutos do YouTube	Tokens do MCP-YouTube	Economia de tokens	Tamanho dos dados
`getChannelStatistics`	673	86	~87% Menos	1,9 KB ➔ 0,2 KB
`getVideoDetails`	854	209	~75% Menos	2,9 KB ➔ 0,6 KB
`searchVideos`	1115	402	~64% Menos	3,4 KB ➔ 1,2 KB

(Curioso? Você pode comparar as respostas brutas da API vs. saídas otimizadas na pasta de exemplos).

🛡️ 2. Proteja Suas Cotas de API (Cache Inteligente)

A API de Dados do YouTube tem limites diários rígidos (10.000 unidades de cota). Se o seu LLM ficar preso em um loop ou repetir uma pergunta, servidores comuns drenarão seu limite de API em minutos. Este servidor inclui uma camada de cache MongoDB opcional. Se o seu agente solicitar detalhes de um vídeo ou pesquisar os mesmos vídeos em alta duas vezes, o servidor atenderá a partir do cache - custando 0 pontos de cota de API.

🏗️ 3. Nível de Produção e Manutenção Ativa

Cansado de ferramentas MCP que derrubam seu cliente de IA? Este servidor foi construído para ser uma dependência sólida como uma rocha:

97% de Cobertura de Testes: Testes unitários abrangentes (veja o selo do Codecov).
Zero Erros/Alertas de Lint: Aplica código estrito e limpo (npm run lint passa 100%).
Segurança Ativa: Patches automatizados do Dependabot garantem que as bibliotecas subjacentes nunca fiquem com vulnerabilidades conhecidas.
Segurança de Tipos Estrita: Construído com validação Zod e a arquitetura robusta do MCP TypeScript Starter.

Início Rápido: Instalação

🟢 Modo Zero-Configuração (Sem Chave de API)

Quer apenas buscar transcrições? Você pode usar este servidor imediatamente, sem qualquer configuração! Basta instalar e usar. Adicione uma chave de API do YouTube depois para desbloquear busca avançada e análises.

A maneira mais fácil de instalar este servidor é clicando no botão "Adicionar ao Claude Desktop" na página do servidor no Glama.

Se você estiver configurando manualmente (ex.: no Cursor), basta adicionar esta configuração mínima:

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@kirbah/mcp-youtube"]
    }
  }
}

✨ Dica: No modo Zero-Configuração, você pode pedir à sua IA para simplesmente "Ler a transcrição de youtube://transcript/{videoId}"!

🟡 Configuração Manual (Desbloqueie Todos os Recursos)

Se você preferir configurar seu cliente MCP manualmente (ex.: Claude Desktop ou Cursor), adicione o seguinte ao seu arquivo de configuração:

Obtenha uma Chave da API de Dados do YouTube v3 (Veja as Instruções de Configuração abaixo).
(Altamente Recomendado) Obtenha uma String de Conexão MongoDB gratuita para habilitar o cache que economiza cota.

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@kirbah/mcp-youtube"],
      "env": {
        "YOUTUBE_API_KEY": "YOUR_YOUTUBE_API_KEY_HERE",
        "MDB_MCP_CONNECTION_STRING": "mongodb+srv://user:pass@cluster0.abc.mongodb.net/youtube_niche_analysis"
      }
    }
  }
}

(Usuários do Windows PowerShell: Se npx falhar, tente usar "command": "cmd" e "args": ["/k", "npx", "-y", "@kirbah/mcp-youtube"])

Próximo Passo: Adicione uma Skill

Depois que seu servidor estiver conectado, experimente o CreatorLens - uma Skill do Claude construída especificamente para este MCP que transforma dados brutos do YouTube em diagnósticos de crescimento (ganchos fracos, embalagem, dúvidas de nicho, mudanças de formato).

Recursos Principais

Informações de Vídeo Otimizadas: Pesquise vídeos com filtros avançados. Recupere metadados detalhados, estatísticas (visualizações, curtidas, etc.) e detalhes de conteúdo, tudo estruturado para um consumo mínimo de tokens.
Gerenciamento Eficiente de Transcrições: Obtenha legendas/subtítulos de vídeos com suporte a vários idiomas, perfeito para análise de conteúdo por LLMs.
Análise de Canais com Insights: Obtenha estatísticas concisas do canal (inscritos, visualizações, contagem de vídeos) e descubra os vídeos de melhor desempenho de um canal sem excesso de dados.
Descoberta de Tendências Enxuta: Encontre vídeos em alta por região e categoria, e obtenha listas de categorias de vídeo disponíveis, otimizadas para processamento rápido por IA.
Estruturado para IA: Todas as respostas são projetadas para serem facilmente analisáveis e imediatamente úteis para modelos de linguagem.
Recuperação Eficiente de Comentários: Obtenha comentários de vídeos com controle refinado sobre o número de resultados e respostas, otimizado para análise de sentimento e extração de feedback.

Ferramentas Disponíveis

O servidor fornece as seguintes ferramentas MCP, cada uma projetada para retornar dados otimizados em tokens:

Nome da Ferramenta	Descrição	Parâmetros (veja detalhes no esquema da ferramenta)
`getVideoDetails`	Recupera informações detalhadas e enxutas de vários vídeos do YouTube, incluindo metadados, estatísticas, índices de engajamento e detalhes de conteúdo.	`videoIds` (array de strings)
`searchVideos`	Pesquisa vídeos ou canais com base em uma string de consulta com várias opções de filtro, retornando resultados concisos.	`query` (string), `maxResults` (número opcional), `order` (opcional), `type` (opcional), `channelId` (opcional), etc.
`getTranscripts`	Recupera transcrições (legendas) eficientes em tokens de vários vídeos, com opções para texto completo ou segmentos-chave (introdução/conclusão).	`videoIds` (array de strings), `lang` (string opcional para código de idioma), `format` (enum opcional: 'full_text', 'key_segments' - padrão 'key_segments')
`getChannelStatistics`	Recupera estatísticas enxutas de vários canais (contagem de inscritos, contagem de visualizações, contagem de vídeos, data de criação).	`channelIds` (array de strings)
`getChannelTopVideos`	Recupera uma lista dos vídeos de melhor desempenho de um canal com detalhes enxutos e índices de engajamento.	`channelId` (string), `maxResults` (número opcional)
`getTrendingVideos`	Recupera uma lista de vídeos em alta para uma região e categoria opcional, com detalhes enxutos e índices de engajamento.	`regionCode` (string opcional), `categoryId` (string opcional), `maxResults` (número opcional)
`getVideoCategories`	Recupera as categorias de vídeo do YouTube disponíveis (ID e título) para uma região específica, fornecendo apenas dados essenciais.	`regionCode` (string opcional)
`getVideoComments`	Recupera comentários de um vídeo do YouTube. Permite ordenar, limitar resultados e buscar um pequeno número de respostas por comentário.	`videoId` (string), `maxResults` (número opcional), `order` (opcional), `maxReplies` (número opcional), `commentDetail` (string opcional)
`findConsistentOutlierChannels`	Identifica canais que consistentemente se destacam como outliers em um nicho específico. Requer uma conexão MongoDB.	`niche` (string), `minVideos` (número opcional), `maxChannels` (número opcional)

Para parâmetros de entrada detalhados e suas descrições, consulte o inputSchema dentro do arquivo de configuração de cada ferramenta no diretório src/tools/ (ex.: src/tools/video/getVideoDetails.ts).

Nota sobre Custos de Cota de API: A maioria das ferramentas é altamente eficiente. getVideoDetails, getChannelStatistics e getTrendingVideos custam apenas 1 unidade por chamada. A ferramenta getTranscripts tem custo de API 0. A nova ferramenta getVideoComments tem custo variável: a chamada base é 1 unidade, mas se você solicitar respostas (definindo maxReplies > 0), custa 1 unidade adicional para cada comentário de nível superior para o qual busca respostas. As ferramentas baseadas em pesquisa são as mais caras: searchVideos custa 100 unidades e getChannelTopVideos custa 101 unidades.

Uso Avançado e Desenvolvimento Local

Se você deseja contribuir, modificar o servidor ou executá-lo localmente fora do ambiente gerenciado de um cliente MCP:

Pré-requisitos

Node.js (versão especificada no campo engines do package.json - atualmente >=22.0.0)
npm (geralmente vem com o Node.js)
Uma Chave da API de Dados do YouTube v3 (veja Configuração da API do YouTube)

Configuração Local

Clone o repositório:

git clone https://github.com/kirbah/mcp-youtube.git
cd mcp-youtube

Instale as dependências:
```
npm ci
```
Configure o Ambiente: Crie um arquivo .env na raiz copiando o .env.example:
```
cp .env.example .env
```
Em seguida, edite o .env para adicionar seu YOUTUBE_API_KEY:
```
YOUTUBE_API_KEY=your_youtube_api_key_here
MDB_MCP_CONNECTION_STRING=your_mongodb_connection_string_here
```

Scripts de Desenvolvimento

# Run in development mode with live reloading
npm run dev

# Build for production
npm run build

# Run the production build (after npm run build)
npm start

# Lint files
npm run lint

# Run tests
npm run test
npm run test -- --coverage # To generate coverage reports

# Inspect MCP server using the Model Context Protocol Inspector
npm run inspector

Desenvolvimento Local com um Cliente MCP

Para fazer um cliente MCP executar sua versão de desenvolvimento local (em vez do pacote NPM publicado):

Certifique-se de ter um script em package.json para uma inicialização sem observação, ex.:
```
"scripts": {
  "start:client": "tsx ./src/index.ts"
}
```
Configure seu cliente MCP para iniciar este script local:
```
{
  "mcpServers": {
    "youtube_local_dev": {
      "command": "npm",
      "args": ["run", "start:client"],
      "working_directory": "/absolute/path/to/your/cloned/mcp-youtube",
      "env": {
        "YOUTUBE_API_KEY": "YOUR_LOCAL_DEV_API_KEY_HERE"
      }
    }
  }
}
```
Nota sobre o bloco env acima: Definir YOUTUBE_API_KEY diretamente no bloco env da configuração do cliente é uma forma de fornecer a chave de API. Alternativamente, se o seu servidor carregar corretamente seu arquivo .env com base no working_directory, você pode não precisar especificá-lo no bloco env do cliente, desde que seu arquivo .env local na raiz do projeto contenha o YOUTUBE_API_KEY. O caminho do working_directory deve ser absoluto e correto para que o servidor encontre seu arquivo .env.

Configuração da API do YouTube

Acesse o Google Cloud Console.
Crie um novo projeto ou selecione um existente.
No menu de navegação, vá para "APIs & Services" > "Library".
Pesquise por "YouTube Data API v3" e ative para o seu projeto.
Vá para "APIs & Services" > "Credentials".
Clique em "+ CREATE CREDENTIALS" e escolha "API key".
Copie a chave de API gerada. Esta é a sua YOUTUBE_API_KEY.
Etapa importante de segurança: restrinja sua chave de API para evitar uso não autorizado. Clique no nome da chave de API e, em "API restrictions", selecione "Restrict key" e escolha "YouTube Data API v3". Você também pode adicionar "Application restrictions" (por exemplo, endereços IP), se aplicável.

Requisitos do sistema

Node.js: >=22.0.0 (conforme especificado em package.json)
npm (para gerenciar dependências e executar scripts)

Aprofundamento: Ferramenta `findConsistentOutlierChannels`

A ferramenta findConsistentOutlierChannels foi projetada para identificar canais do YouTube emergentes ou estabelecidos que consistentemente superam seu tamanho em um nicho específico. Essa ferramenta é particularmente útil para criadores de conteúdo, profissionais de marketing e analistas que buscam canais de alto potencial.

Observação importante: esta ferramenta requer uma conexão MongoDB para armazenar e analisar dados de canais. Sem MDB_MCP_CONNECTION_STRING configurado, esta ferramenta não estará disponível.

Visão geral da lógica interna

A ferramenta opera por meio de um processo de análise em várias fases, utilizando tanto a YouTube Data API quanto um banco de dados MongoDB:

Busca de candidatos (Fase 1):
- Usa o query fornecido para pesquisar vídeos e canais relevantes no YouTube.
- Filtra os resultados iniciais com base em videoCategoryId e regionCode, se especificados.
- Coleta um conjunto amplo de canais potenciais para análise mais aprofundada.
Filtragem de canais (Fase 2):
- Recupera estatísticas detalhadas dos canais candidatos (inscritos, visualizações totais, número de vídeos).
- Filtra canais com base em channelAge (por exemplo, 'NEW' para canais com menos de 6 meses, 'ESTABLISHED' para 6 a 24 meses).
- Garante que os canais atendam a um número mínimo de vídeos para serem considerados na consistência.
Análise aprofundada (Fase 3):
- Para cada canal filtrado, busca os vídeos recentes de melhor desempenho.
- Calcula um "fator viral" para cada vídeo (por exemplo, visualizações em relação ao número de inscritos).
- Avalia o consistencyLevel (por exemplo, 'MODERATE' para ~30% dos vídeos com desempenho discrepante, 'HIGH' para ~50%).
- Determina o outlierMagnitude (por exemplo, 'STANDARD' para visualizações > inscritos, 'STRONG' para visualizações > 3x inscritos).
Classificação e formatação (Fase 4):
- Classifica os canais com base na consistência, magnitude das discrepâncias e desempenho geral no nicho.
- Formata os resultados em uma estrutura otimizada para tokens, adequada para LLMs, incluindo métricas-chave dos canais e exemplos de vídeos discrepantes.

Principais parâmetros que controlam o fluxo

O comportamento desta ferramenta é controlado principalmente pelos seguintes parâmetros:

query (string, obrigatório): o tópico ou nicho central a ser analisado (por exemplo, "reparos domésticos DIY", "computação quântica explicada").
channelAge (enum: "NEW", "ESTABLISHED", padrão: "NEW"): concentra a busca em canais emergentes ou mais maduros.
consistencyLevel (enum: "MODERATE", "HIGH", padrão: "MODERATE"): define o limite para o quão consistentemente os vídeos de um canal devem ter desempenho discrepante.
outlierMagnitude (enum: "STANDARD", "STRONG", padrão: "STANDARD"): define o quanto o desempenho de um vídeo deve exceder as expectativas típicas (por exemplo, visualizações vs. inscritos) para ser considerado uma "discrepância".
videoCategoryId (string, opcional): restringe a busca a um ID de categoria específico do YouTube.
regionCode (string, opcional): direciona canais relevantes para uma região geográfica específica.
maxResults (número, padrão: 10): limita o número de principais canais discrepantes retornados.

Considerações de segurança

Segurança da chave de API: sua YOUTUBE_API_KEY é sensível. Nunca a envie diretamente para o repositório. Use variáveis de ambiente (por exemplo, por meio de um arquivo .env, que deve ser listado em .gitignore).
Cotas da API: a YouTube Data API tem uma cota de uso diária (o padrão é 10.000 unidades). Todas as chamadas de ferramentas deduzem dessa cota. Monitore seu uso no Google Cloud Console e esteja atento ao custo de cada ferramenta. Para um detalhamento dos custos por método de API, consulte a documentação oficial.
Validação de entrada: o servidor usa Zod para validação robusta de entrada em todos os parâmetros das ferramentas, aumentando a segurança e a confiabilidade.

Licença

Este projeto é licenciado sob a Licença MIT. Consulte o arquivo LICENSE para obter detalhes.