HasData YouTube MCP Server

Servidor MCP do YouTube

Um servidor de Model Context Protocol (MCP) hospedado que oferece ao Claude, Cursor, Windsurf e qualquer outro cliente MCP quatro ferramentas somente leitura do YouTube. Pesquise no YouTube, leia dados de vídeos e canais e obtenha transcrições, sem projeto no Google Cloud e sem chave da API de Dados do YouTube.

https://mcp.hasdata.com/api/mcp?apis=youtube

Conteúdo

• O que você precisa
• Início rápido
• Exemplos de prompts
• Ferramentas
• Erros e caminhos de falha
• Preços, plano gratuito e limites
• Seleção de ferramentas
• Comparação
• Perguntas frequentes
• Links do HasData
• Desenvolvimento
• Contribuição
• Licença

O que você precisa

Um cliente MCP que fale HTTP transmissível com cabeçalhos personalizados. Uma chave de API do HasData do painel de controle, gratuita para criar. Nada mais. Este é um servidor remoto, então o caminho mais simples é uma URL e um cabeçalho, sem contêiner para executar e sem conta do Google em nenhum lugar do fluxo. Um cliente somente stdio pode usar o inicializador @hasdata/youtube-mcp (npm) ou hasdata-youtube-mcp (PyPI).

Início rápido

A URL do servidor é a mesma para todos os clientes. Nós a executamos na prática no Claude Code e no Claude Desktop. Os outros blocos seguem o formato documentado de cada cliente para um servidor remoto.

Clientes com suporte a OAuth podem adicionar a mesma URL como conector e entrar sem colocar uma chave em um arquivo de configuração.

claude mcp add --transport http youtube "https://mcp.hasdata.com/api/mcp?apis=youtube" \
  --header "x-api-key: HASDATA_API_KEY"

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@hasdata/youtube-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

{
  "mcpServers": {
    "youtube": {
      "command": "uvx",
      "args": ["hasdata-youtube-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

{
  "mcpServers": {
    "youtube": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=youtube",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

{
  "mcpServers": {
    "youtube": {
      "serverUrl": "https://mcp.hasdata.com/api/mcp?apis=youtube",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

{
  "mcpServers": {
    "youtube": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=youtube",
      "type": "streamableHttp",
      "headers": { "x-api-key": "HASDATA_API_KEY" },
      "disabled": false
    }
  }
}

{
  "servers": {
    "youtube": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=youtube",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

[mcp_servers.youtube]
url = "https://mcp.hasdata.com/api/mcp?apis=youtube"

[mcp_servers.youtube.headers]
"x-api-key" = "HASDATA_API_KEY"

{
  "mcpServers": {
    "youtube": {
      "httpUrl": "https://mcp.hasdata.com/api/mcp?apis=youtube",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

Exemplos de prompts

Prompts, não código. Cole um e o agente escolhe a ferramenta sozinho. Cada um é anotado com as chamadas que faz, porque no MCP o modelo decide quantas chamadas fazer e cada chamada bem-sucedida custa 10 créditos.

Encontre os dez vídeos mais vistos sobre o Model Context Protocol do último mês, depois obtenha a transcrição do primeiro e me dê as três afirmações que ele faz sobre chamadas de ferramentas.

Duas chamadas, 20 créditos.

Pegue o canal @GoogleDevelopers. Liste as abas que ele publica, depois resuma os últimos cinco uploads e me diga quais tópicos se repetem.

Duas chamadas, 20 créditos. Ler uma aba que você ainda não viu exige uma segunda chamada, porque a lista de abas chega dentro da primeira resposta.

Pegue este id de vídeo, dQw4w9WgXcQ. Obtenha as estatísticas dele e depois verifique quais dos vídeos relacionados vêm do mesmo canal.

Uma chamada, 10 créditos. Os vídeos relacionados vêm junto na mesma resposta.

Pesquise no YouTube por "web scraping tutorial", ordenado por data de upload, vídeos com menos de quatro minutos apenas, e me dê os títulos dos capítulos de cada resultado que os tiver.

Uma chamada, 10 créditos.

Obtenha a transcrição em alemão deste vídeo se existir, e me diga em quais idiomas ele está disponível.

Uma chamada, 10 créditos.

A pesquisa aceita os próprios tokens de filtro do YouTube, e um agente restringe por duração, data de upload e tipo de conteúdo sem pós-processamento. As transcrições chegam com a lista de faixas de idioma disponíveis, o que permite ao agente escolher uma sem adivinhar.

Paginção custa uma chamada cada vez. Um prompt de pesquisa que busca, pagina duas vezes e depois obtém três transcrições é seis chamadas e 60 créditos. O teste gratuito rende mais em perguntas específicas do que em varreduras abertas.

Ferramentas

Quatro ferramentas, todas somente leitura. Os exemplos abaixo são reduzidos de chamadas reais, e os números neles mudam conforme o YouTube atualiza. Leia-os como formatos. Cada nome de ferramenta linka para a referência do endpoint, que traz a lista completa de campos.

Os exemplos são o payload, não a resposta inteira. Um resultado tools/call carrega um bloco de texto, e esse texto é em si JSON contendo url, status, text e json, com os dados extraídos sob json. De uma resposta JSON-RPC bruta, o caminho é result.content[0].text, analisado, depois .json. Um cliente de chat desembrulha isso para você, e código que fala diretamente com o endpoint não faz.

Obter resultados de pesquisa do YouTube

hasdata_youtube_search_getYoutubeSearchResults

Pesquisa no YouTube e retorna a página inteira de resultados, dividida por tipo de resultado.

Uma página de resultados é dividida entre videoResults, shortsResults, inlineShortsResults, playlistResults, channelResults e shelves, com posicionamentos pagos em adsResults e sponsoredResults. Quais blocos aparecem dependem da consulta, e um bloco sem nada para reportar está ausente, não vazio. Teste a chave antes de iterar. searchInformation carrega o total e pagination.nextPageToken é o que você realimenta como paginationToken. Anúncios nunca se misturam aos arrays orgânicos, embora haja dois deles para pular.

{
  "positionOnPage": 1,
  "videoId": "GuTcle5edjk",
  "title": "you need to learn MCP RIGHT NOW!! (Model Context Protocol)",
  "viewsOriginal": "1.6M views",
  "views": 1653824,
  "length": "38:40",
  "publishedDate": "11 months ago",
  "extensions": ["4K"],
  "chapters": [
    { "title": "Intro", "time": "0:00" },
    { "title": "Problem: LLMs Suck at Accessing Code", "time": "0:40" }
  ],
  "channel": { "name": "NetworkChuck", "verified": true }
}

Duas coisas ali merecem menção. views é um inteiro analisado ao lado da string de exibição 1.6M views e não precisa de analisador de sufixo. E chapters vêm dentro dos resultados de pesquisa, não apenas no próprio vídeo, embora apenas alguns vídeos os carreguem.

A referência do endpoint de pesquisa lista todos os tokens sp e filters__ que o endpoint aceita.

Obter dados de vídeo do YouTube

hasdata_youtube_video_getYoutubeVideo

Um vídeo por id.

Retorna title, thumbnail, channel, publishedDate, lengthSeconds, category, isFamilySafe e isUnlisted, mais os arrays relatedVideos, endScreenVideos, keywords, captions, music e socialLinks. description é um objeto que contém o texto completo em content e um array links onde cada link e hashtag carrega startIndex, length, text e url. O campo text contém o link como o autor o escreveu e url contém o invólucro de redirecionamento do YouTube, o que importa se você estiver extraindo destinos de patrocinadores ou afiliados das descrições.

Leia o campo analisado pelo nome por ferramenta antes de copiar o exemplo abaixo. Resultados de pesquisa e canal colocam o número analisado em views e a string de exibição em viewsOriginal. Esta resposta inverte isso, mantendo a string em views e o número em extractedViews, e a mesma inversão se aplica a likes e subscribers. Erre isso e item.views > 100000 compara uma string aqui sem nunca lançar erro.

{
  "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
  "views": "1,806,075,152 views",
  "extractedViews": 1806075152,
  "likes": "19M",
  "extractedLikes": 19344370,
  "publishedDate": "Oct 24, 2009",
  "lengthSeconds": 214,
  "category": "Music",
  "channel": { "name": "Rick Astley", "subscribers": "4.53M subscribers", "extractedSubscribers": 4530000 }
}

Obter dados de canal do YouTube

hasdata_youtube_channel_getYoutubeChannel

Um canal por id ou handle, uma aba por vez.

Retorna channelInfo, featuredVideo e sections na aba padrão. Outras abas retornam seu próprio formato. channelInfo carrega o handle, avatar, banner, descrição, palavras-chave do canal e o rssUrl do canal, suficiente para continuar acompanhando um canal sem consultá-lo repetidamente.

O array availableTabs no exemplo abaixo contém rótulos de exibição, e eles não são os valores que tab aceita. Home, Live, Courses e Search não correspondem a nenhum valor de parâmetro, e o restante precisa de minúsculas. Um agente que lê a lista e percorre cada entrada falha na primeira.

{
  "channelInfo": {
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "name": "Google for Developers",
    "handle": "@GoogleDevelopers",
    "rssUrl": "https://www.youtube.com/feeds/videos.xml?channel_id=UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "isFamilySafe": true,
    "availableTabs": ["Home", "Videos", "Shorts", "Live", "Courses", "Playlists", "Posts", "Search"]
  }
}

Obter transcrição de vídeo do YouTube

hasdata_youtube_transcript_getYoutubeTranscript

A transcrição cronometrada de um vídeo.

Verifique selected na resposta antes de confiar no idioma. Pedir um languageCode que o vídeo não carrega não falha nem retorna vazio; ele silenciosamente volta para a faixa padrão. Cada entrada na lista carrega languageName e languageCode, e um idioma pode aparecer duas vezes, uma com autoria humana e outra com type definido como asr.

{
  "transcript": [
    { "startMs": 320, "endMs": 18800, "snippet": "[Music]", "startTimeText": "0:00" },
    { "startMs": 18800, "endMs": 21800, "snippet": "We're no strangers to", "startTimeText": "0:18" }
  ],
  "availableTranscripts": [
    { "languageName": "English", "languageCode": "en" },
    { "languageName": "English", "languageCode": "en", "type": "asr", "selected": true },
    { "languageName": "German (Germany)", "languageCode": "de-DE" },
    { "languageName": "Japanese", "languageCode": "ja" }
  ]
}

Erros e caminhos de falha

Seu cliente quase nunca vê um código de erro HTTP vindo de uma chamada de ferramenta. A camada MCP responde com 200 e coloca a falha dentro do resultado, com isError definido como true e o motivo como texto. O agente lê uma mensagem onde você poderia esperar uma linha de status.

Uma chave errada aparece como saída da ferramenta, não como uma conexão falha. tools/list aceita qualquer chave não vazia e retorna todas as quatro ferramentas, então o cliente completa o handshake e mostra verde. A primeira chamada de ferramenta então retorna com isError: true e o texto HasData API error: 401 Unauthorized. Fique atento a essa string, porque nada antes no fluxo relata o problema.

Uma chave ausente é o único erro HTTP real. A autorização roda antes de qualquer ferramenta, e a própria conexão falha com 401. Os cabeçalhos CORS estão presentes, e um cliente de navegador lê o status e não uma falha de rede opaca.

Um argumento que quebra o schema de uma ferramenta é rejeitado antes de virar um scrape. O servidor responde com isError: true e o texto MCP error -32602: Input validation error, nomeando o campo problemático. Nada é buscado e nada é cobrado. A mensagem nomeia o campo, mas não os valores aceitos, então as tabelas de parâmetros acima são a referência.

Uma chamada que tem sucesso e não encontra nada é o caso que pega as pessoas de surpresa. Ela chega como um resultado comum com requestMetadata.status definido como ok e a chave de dados simplesmente ausente. Nada no corpo diz que o resultado estava vazio. Teste pelo campo que você precisa, não por um erro.

Um identificador que a plataforma rejeita retorna 400 com requestMetadata.status definido como error. Um handle de canal que não existe é a forma mais comum de ver isso.

Resultados que carregam dados também carregam um requestMetadata.id que vale a pena citar no suporte.

Preços, camada gratuita e limites

Cada ferramenta do YouTube custa 10 créditos por chamada bem-sucedida. O tamanho da resposta não muda o preço. Uma página cheia de resultados de busca custa o mesmo que uma página com um vídeo.

O teste gratuito é 1.000 créditos por 30 dias sem cartão, o que equivale a 100 chamadas do YouTube. Depois disso, uma conta ativa continua recebendo 100 créditos recarregados diariamente sempre que o saldo cair abaixo de 100, então um agente de baixo volume roda na camada gratuita indefinidamente.

Os planos pagos começam em US$ 49 por mês para 200.000 créditos, o que equivale a 20.000 chamadas. O preço unitário cai com o volume, de US$ 2,45 por 1.000 chamadas no plano inicial para US$ 0,99 no Business, US$ 0,83 no Growth e US$ 0,75 nos maiores planos de alto volume.

Seu plano também define a concorrência. O teste gratuito permite 1 requisição por vez, o Startup 15, o Business 30, o Growth 50, e os planos de alto volume vão de 200 a 1.500. Trate o caso de estouro defensivamente em qualquer coisa não supervisionada, porque um agente que se espalha vai atingir o teto antes de você.

Uma requisição que retorna não-200 não é cobrada. Uma chamada bem-sucedida que não encontra nada ainda é uma chamada.

Seleção de ferramentas

O parâmetro de consulta apis decide quais ferramentas seu agente vê. Menos ferramentas significa menos contexto gasto em definições de ferramentas e menos chances de o modelo escolher a errada.

?apis=youtube                    the four tools in this repo
?apis=youtube,google_serp        add Google search
?apis=youtube,tiktok,instagram   a social research bundle

O parâmetro aceita nomes de provedores como youtube e nomes de APIs individuais como google_maps_search. Nomes com erro de digitação são ignorados. Se todos os nomes estiverem errados, a requisição falha com 400, e o corpo lista tanto o que não foi reconhecido quanto todos os valores válidos. Remova o parâmetro e o mesmo endpoint expõe todas as 57 ferramentas do HasData.

Como se compara

Contra a oficial YouTube Data API v3:

As duas últimas linhas importam. Se a cota diária cobre seu volume e você é dono do canal que está consultando, a API oficial é a resposta mais barata e você deve usá-la.

A maioria dos outros servidores MCP do YouTube faz apenas transcrições. Este também busca, lê vídeos com seus números de engajamento e percorre abas de canais, então um agente roda uma passada inteira de pesquisa sem um segundo servidor.

O que este servidor não faz. Sem comentários, sem gerenciamento de canais, sem uploads, sem análises, sem dados privados. Ele lê o que um visitante desconectado pode ver.

FAQ

Existe um servidor MCP oficial do YouTube?

O Google não publica um. O YouTube não tem um servidor MCP de primeira parte. Toda opção é construída por outra pessoa, seja em torno da YouTube Data API v3 ou das páginas públicas. Este é mantido pela HasData e lê páginas públicas, por isso não precisa de credenciais do Google.

O que é um servidor MCP do YouTube?

Um servidor que expõe dados do YouTube como ferramentas que um cliente de IA pode chamar. O cliente envia uma chamada de ferramenta pelo Model Context Protocol, o servidor busca os dados e retorna JSON estruturado, e o modelo trabalha com o resultado e nunca vê uma página de HTML. Este expõe quatro ferramentas e roda remotamente. O cliente se conecta a uma URL e não inicia nenhum processo local.

Preciso de uma chave da API do YouTube ou de um projeto no Google Cloud?

Não. A única credencial é sua chave da HasData. Não há projeto no Google Cloud para criar, formulário de cota para preencher ou tela de consentimento OAuth, porque as ferramentas leem páginas públicas do YouTube e não a YouTube Data API.

Preciso hospedar ou executar algo?

Não. Este é um servidor MCP remoto em HTTP streamable. Nada para instalar, nenhum contêiner para manter aquecido, nenhum processo para reiniciar.

Os dados são ao vivo ou em cache?

Ao vivo. Cada chamada busca a página no momento da requisição e carrega seu próprio requestMetadata.id. Duas chamadas idênticas são duas buscas separadas e não uma reprodução de uma cópia armazenada. Contadores como visualizações e curtidas acompanham a página, então eles se movem conforme a página se move.

O que acontece quando o YouTube muda seu layout?

Nada do seu lado. Nós acompanhamos as mudanças e mantemos o schema de resposta estável, então nomes de campos e tipos permanecem no lugar. Um campo sem valor está ausente do item, não presente e nulo. Leia campos opcionais com um valor padrão.

Posso usar isso junto com outras APIs da HasData?

Sim. O parâmetro apis aceita uma lista, e ?apis=youtube,google_serp dá ao seu agente as quatro ferramentas do YouTube mais a busca do Google. Remova o parâmetro e você obtém tudo.

Posso obter uma transcrição para qualquer vídeo?

Somente onde o vídeo tem uma, e availableTranscripts informa o que existe antes de você pedir.

Posso entrar com OAuth em vez de colar uma chave?

Sim, em clientes que suportam isso. Claude Desktop e Cursor podem adicionar o endpoint como um conector e entrar. Agentes não supervisionados e scripts usam o cabeçalho x-api-key.

Conformidade e dados pessoais

A HasData acessa apenas dados publicamente disponíveis. Os termos de uma plataforma podem restringir o acesso automatizado, e você é responsável pela sua própria conformidade. Onde os dados que você coleta incluem informações pessoais, certifique-se de ter uma base legal para isso sob o GDPR, CCPA ou as regras equivalentes na sua jurisdição.

Links da HasData

Desenvolvimento

Este repositório é configuração e documentação para um servidor remoto. Não há etapa de build e nada para containerizar.

Os testes em test/ verificam o contrato da ferramenta, a parte que pode quebrar sem um commit aqui. Eles verificam que ?apis=youtube retorna exatamente quatro ferramentas, que toda ferramenta ainda declara seu parâmetro obrigatório, que nenhum nome mudou e que a chave em uso é realmente aceita. Esse último check chama uma ferramenta de verdade e custa 10 créditos, que é o preço de um canário que pode falhar pelo motivo certo.

# macOS and Linux
HASDATA_API_KEY=your_key_here npm test

# Windows PowerShell
$env:HASDATA_API_KEY="your_key_here"; npm test

A mesma suíte roda no CI a cada push e uma vez por semana em um cronograma, porque a lista de ferramentas upstream pode mudar sem ninguém tocar neste repositório. Uma falha significa que a lista de ferramentas mudou, a chave parou de funcionar ou o endpoint estava inacessível, e a mensagem de asserção diz qual.

Contribuindo

Correções nas tabelas de ferramentas e nos exemplos de resposta são a contribuição mais útil, porque essas são as partes que se desatualizam. Inclua a chamada que você fez e a resposta que obteve. Pull requests de forks rodam a suíte sem chave, e os checks ao vivo pulam em vez de ficarem vermelhos.

Licença

MIT. Veja LICENSE.