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.

1.000 créditos gratuitos todos os meses, sem necessidade de cartão, o que equivale a 100 chamadas ao YouTube.

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

• Prompts e recursos

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
• Como ele se compara
• Perguntas frequentes
• Links do HasData
• Desenvolvimento
• Contribuição
• Licença

O que você precisa

Um cliente MCP que fale HTTP transmití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 o 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/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/mcp?apis=youtube",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

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

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

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

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

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

{
  "mcpServers": {
    "youtube": {
      "httpUrl": "https://mcp.hasdata.com/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 por conta própria. Cada um é anotado com as chamadas que ele 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 assistidos sobre o Model Context Protocol do último mês, depois extraia 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 guias que ele publica, depois resuma os últimos cinco uploads e me diga quais tópicos se repetem.

Duas chamadas, 20 créditos. Ler uma guia que você ainda não viu exige uma segunda chamada, porque a lista de guias 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 "tutorial de web scraping", ordenado por data de upload, apenas vídeos com menos de quatro minutos, e me dê os títulos dos capítulos de cada resultado que os tiver.

Uma chamada, 10 créditos.

Extraia 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 refina 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 idiomas disponíveis, o que permite ao agente escolher uma sem adivinhar.

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

Ferramentas

Quatro ferramentas, todas somente leitura. As amostras abaixo são extraídas de chamadas reais, e os números nelas mudam conforme o YouTube é atualizado. Leia-as como formatos. O nome de cada ferramenta vincula à referência do endpoint, que traz a lista completa de campos.

As amostras são o payload, não a resposta inteira. Um resultado de 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 de resultados inteira, 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 a relatar está ausente, não vazio. Teste a chave antes de iterar. searchInformation carrega o total e pagination.nextPageToken é o que você realimenta como paginationToken. Os 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, além dos 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 wrapper 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 a amostra abaixo. Os 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. Se errar, 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 guia por vez.

Retorna channelInfo, featuredVideo e sections na guia padrão. Outras guias retornam seu próprio formato. channelInfo carrega o handle, avatar, banner, descrição, palavras-chave do canal e o rssUrl do canal, o suficiente para continuar acompanhando um canal sem fazer polling.

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 mapeiam para nenhum valor de parâmetro, e o restante precisa ser convertido para 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. Solicitar um languageCode que o vídeo não possui não falha nem retorna vazio; ele silenciosamente volta para a faixa padrão. Cada entrada na lista contém languageName e languageCode, e um idioma pode aparecer duas vezes, uma vez 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" }
  ]
}

Prompts e recursos

O servidor oferece 2 prompts, fluxos de trabalho prontos que um cliente pode oferecer em vez de fazer o usuário compor uma chamada de ferramenta.

Junto com eles, o servidor expõe 10 recursos, um por parâmetro cujos valores aceitos são uma lista fixa. Ler um deles é mais barato do que aprender o vocabulário a partir de uma chamada rejeitada, e não custa créditos. Cada URI é hasdata://youtube/<parameter>.

Ambas as listas são servidas sem chave de API, então um cliente pode lê-las antes de o usuário se cadastrar.

Erros e caminhos de falha

Seu cliente quase nunca vê um código de erro HTTP 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 ocorre 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 esquema de uma ferramenta é rejeitado antes de se tornar uma raspagem. 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 é bem-sucedida e não encontra nada é o caso que confunde as pessoas. 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 o campo que você precisa, não 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 maneira usual de ver isso.

Resultados que contêm dados também trazem 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 pesquisa custa o mesmo que uma página com um vídeo.

A camada gratuita é de 1.000 créditos todo mês sem cartão, o que equivale a 100 chamadas do YouTube. Ela se renova com o ciclo de cobrança, então um agente de baixo volume roda na camada gratuita indefinidamente.

Os planos pagos começam em US$ 59 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,95 por 1.000 chamadas no plano inicial para US$ 1,19 no Basic e US$ 0,83 nos níveis Growth. Os valores atuais estão na página de preços.

Seu plano também define a concorrência. A camada gratuita permite 1 solicitação por vez, Startup 5, Basic 15, e os níveis Growth vão de 50 a 500. Trate o caso de estouro defensivamente em qualquer coisa não supervisionada, porque um agente que se expande atingirá o teto antes de você.

Uma solicitaçã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 alcançar 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 erros de digitação são ignorados. Se todos os nomes estiverem errados, a solicitaçã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 pesquisa, lê vídeos com seus números de engajamento e percorre abas de canais, então um agente executa 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 de API do YouTube ou de um projeto no Google Cloud?

Não. A única credencial é sua chave 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 solicitaçã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 esquema de resposta estável, então nomes e tipos de campos permanecem. Um campo sem valor está ausente do item, não presente e nulo. Leia campos opcionais com um 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 pesquisa 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 e scripts não supervisionados usam o cabeçalho x-api-key.

Conformidade e dados pessoais

A HasData acessa apenas dados disponíveis publicamente. 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 eles sob o GDPR, CCPA ou as regras equivalentes na sua jurisdição.

Links da HasData

Desenvolvimento

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

Os testes em test/ verificam o contrato das ferramentas, a parte que pode quebrar sem um commit aqui. Eles verificam que ?apis=youtube retorna exatamente quatro ferramentas, que cada ferramenta ainda declara seu parâmetro obrigatório, que nenhum nome mudou e que a chave em uso é realmente aceita. Essa última verificação 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 na CI a cada push e uma vez por semana em um agendamento, porque a lista de ferramentas upstream pode mudar sem que ninguém toque neste repositório. Uma falha significa que a lista de ferramentas mudou, a chave parou de funcionar ou o endpoint ficou inacessível, e a mensagem de asserção indica qual é o caso.

Contribuindo

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

Licença

MIT. Veja LICENSE.