Os olhos e ouvidos das redes sociais, orgânicas e pagas, dentro do seu código. Leia qualquer post, descubra o que está em alta, espione anúncios de concorrentes e gere cortes, com as mesmas ferramentas que o Claude e o ChatGPT usam.
POSThttps://viralrecast.com/mcp
Começo rápido
É um endpoint só. Você manda um POST com JSON-RPC 2.0 dizendo qual ferramenta quer usar e com quais argumentos, e recebe o resultado em JSON. Não tem SDK para instalar.
1. Pegue sua chave
Entre na sua conta e copie a chave em viralrecast.com/connect. Ela começa com vr_. Toda conta nova ganha créditos grátis para testar.
O resultado vem em result.structuredContent (JSON pronto para usar). O mesmo conteúdo vem como texto em result.content[0].text, que é o que os assistentes de IA leem: um aviso de conteúdo de terceiros e o JSON entre <<<EXTERNAL CONTENT>>> e <<<END>>>. Toda resposta cobrada traz credits_charged.
Também funcionam: tools/list (ferramentas e o schema de cada uma), initialize, ping e lotes (um array de mensagens num POST só). O endpoint é o servidor MCP do ViralRecast (Streamable HTTP, sem stream SSE): qualquer cliente MCP fala com ele sem adaptação.
Conteúdo orgânico
read_post
Custa 20 créditos (2 se o post já foi lido nas últimas 6 horas).
Lê qualquer post pelo link (TikTok, Instagram reel/carrossel/foto, YouTube, X, Threads, LinkedIn, Reddit) e devolve o conteúdo inteiro para você analisar: transcrição com tempos (da própria rede ou, se ela não legendou, transcrição automática do áudio), as imagens do carrossel (como imagens, para você ver) e o texto escrito em cada slide, comentários mais curtidos, métricas, resumo, pontos-chave, mapa mental e o Viral Score (quão fora da curva o post foi para o tamanho do autor). Use sempre que o usuário colar um link ou pedir para resumir, entender, estudar ou comparar um post. Grava no histórico do usuário.
Parâmetro
Tipo
Descrição
urlobrigatóriostring
string
Link do post
nichestring
string
Tema/nicho de referência do usuário, para a nota de encaixe (fit)
Ver exemplo de resposta (structuredContent, encurtado)
json
{
"id": 73,
"platform": "youtube",
"format": "video",
"url": "https://www.youtube.com/watch?v=KvLWuK2TU-w",
"author": { "handle": "HTXStudio", "name": "HTX Studio", "followers": 2830000 },
"title": "We Built the Product Apple Gave Up On...",
"duration_s": 325,
"published_at": "2026-09-24T12:00:31Z",
"metrics": { "views": 5939233, "likes": 95213, "comments": 3400, "shares": 0, "saves": 0 },
"slides": [],
"transcript": [
{ "start": 0.2, "end": 29.8, "text": "For the past 2 months, I have been building a desk. To understand what it..." },
{ "start": 30.1, "end": 59.6, "text": "..." }
],
"transcript_text": null,
"transcript_note": "Transcrição completa em "transcript", em blocos de ~30 s (start/end em segundos).",
"transcript_source": "platform",
"top_comments": [{ "text": "2027 Apple Airdesk - Starting At $99,999", "likes": 8700, "author": "@..." }],
"analysis": {
"hook": "...", "summary": "...", "key_points": ["..."], "mind_map": "# ...",
"pattern": "história", "emotion": "admiração", "hook_score": 8,
"why_it_worked": "...", "how_to_adapt": ["..."]
},
"score": { "viral_index": 100, "tier": "fora_da_curva", "outlier": 31.31, "final_score": 21.92 },
"from_memory": true,
"credits_charged": 2,
"dashboard_url": "https://viralrecast.com/p/73"
}
read_posts
Custa 20 créditos por post novo e 2 por post lido nas últimas 6 horas (como o read_post).
Lê de 1 a 50 posts de uma vez (para comparar vários posts, um perfil ou uma campanha). Cada chamada lê alguns links em série (até cerca de 25 segundos) e devolve até 5 dossiês prontos, no mesmo formato do read_post e sem as imagens, junto com o batch_id, o status e o que falta. Se a resposta pedir, chame read_posts de novo só com o batch_id, até o status ser done e não haver mais dossiê a receber: não repita os links e não use read_post para os que faltam. Se o status for no_credits, avise o usuário para recarregar e chame de novo com o mesmo batch_id. Para desistir do lote aberto, chame com batch_id e cancel true: os links que faltam são descartados sem custo. Links repetidos ou não reconhecidos não custam nada. Se a conta já tem um lote aberto, a chamada devolve o batch_id dele.
Parâmetro
Tipo
Descrição
urlsstring[]
string[]
Links dos posts (1 a 50), só na primeira chamada
batch_idstring
string
Para continuar um lote: o batch_id devolvido antes (no lugar de urls)
nichestring
string
Tema/nicho de referência do usuário, para a nota de encaixe (fit)
cancelboolean
boolean
Com batch_id: descarta o lote aberto, sem custo para o que faltava
Marca, lista, pausa, religa ou remove os perfis do Instagram e do TikTok que a conta acompanha (o perfil do cliente e dos concorrentes). Cada perfil ativo gera um resumo toda segunda (veja weekly_digest) e chega por e-mail. Só nos planos pagos, com limite de perfis ativos por plano. Em add, informe o link ou o @ do perfil e, se o nome do perfil não achar a página certa na Biblioteca de Anúncios da Meta, o anunciante (nome ou id numérico da página). Marcar um perfil que já está marcado devolve o existente.
Parâmetro
Tipo
Descrição
actionobrigatóriostring
string
O que fazer
addlistpauseresumeremove
profilestring
string
Link ou @ do perfil (em add, pause, resume e remove)
advertiserstring
string
Opcional em add: anunciante da Meta (nome ou id numérico da página)
Custa 80 créditos ao gerar com post ou anúncio novo e 8 se não houver nada novo, uma vez por resumo (as leituras internas não cobram à parte).
O resumo semanal dos perfis acompanhados: posts novos com métricas e Viral Score, os 3 melhores lidos por inteiro (gancho, por que funcionou, link do dossiê), anúncios ativos e novos da Meta e a página achada. Sem profile, devolve o último resumo de cada perfil. Com generate true e um profile, gera o resumo da semana atual (cerca de 25 segundos por chamada: se o status vier running, chame de novo); se já existe um resumo da semana ou de menos de 7 dias, devolve o existente sem cobrar. Ler resumos já gerados é grátis.
Parâmetro
Tipo
Descrição
profilestring
string
Link ou @ do perfil acompanhado
generateboolean
boolean
Gerar o resumo da semana atual (cobra; exige profile)
Conteúdos parecidos com um post já lido, na memória coletiva do ViralRecast (tudo o que já foi consultado na plataforma). Informe o content_id devolvido por read_post.
Custa 4 créditos por rede; x custa 8 e instagram_carousel custa 100 (descobre autores pela hashtag e lê a grade deles).
Busca posts em alta sobre um tema e ranqueia pelo trend_score (alcance + engajamento + viralidade relativa ao tamanho do criador). Redes: tiktok, instagram (Reels), youtube, x, threads, reddit e instagram_carousel (carrosséis e fotos do Instagram). Sem platforms busca em tiktok, instagram, youtube e x. Use instagram_carousel quando o usuário pedir carrossel/foto, reddit ou threads quando pedir discussão/texto.
Parâmetro
Tipo
Descrição
queryobrigatóriostring
string
Tema ou palavra-chave, ex.: "marketing para dentistas"
País, ISO-3166 (BR, US, PT...): filtra o TikTok por país e o X por idioma (BR = português). Omita para global. Use BR quando o usuário falar português e quiser o mercado brasileiro
min_followersinteger
integer
Só criadores com pelo menos N seguidores
Intervalo: 0+
exactboolean
boolean
Busca o texto exatamente como veio, sem corrigir a digitação (padrão false: o tema é corrigido e a resposta traz expanded_terms)
max_followersinteger
integer
Só criadores com até N seguidores. Use quando o usuário pedir perfis pequenos, micro-criadores ou prospecção (ex.: 10000). Os resultados trazem author.followers verificado; não chame analyze_creator só para conferir seguidores.
Custa 5 créditos por página de resultados consultada no Reddit e no YouTube e 10 por página no X; cobra só as páginas que responderam (o padrão, Reddit com posts e comentários e limit 25, custa de 10 a 25).
Use para monitorar menções a uma marca, concorrente, produto ou tema: o que as pessoas estão dizendo, com o mais novo primeiro. Diferente de search_viral_content, que busca o que está em alta e ordena por alcance, aqui o termo é buscado como frase exata e só volta o que cita o termo no texto ou no título (comentários, reclamações, comparações, pedidos de indicação). Redes: reddit (posts e comentários; comentários são o principal sinal), x (posts e respostas) e youtube (vídeos; comentários do YouTube não são pesquisáveis por termo). linkedin ainda não tem busca confiável e volta em errors, sem custo. Cada resultado traz rede, tipo (post ou comment), link, texto, título do post (num comentário, o do post-pai), comunidade, data, pontuação e respostas; nunca traz o autor. Só planos pagos (no Free a tool responde com o link de upgrade).
Parâmetro
Tipo
Descrição
queryobrigatóriostring
string
Termo exato a monitorar, ex.: "SendGrid" ou "Acme Mail". Aspas internas são aceitas: cada trecho entre aspas e cada palavra solta precisam aparecer (ex.: "Acme Mail" suspensa)
platformsstring[]
string[]
Redes (padrão: reddit)
redditxyoutubelinkedin
kindstring
string
posts, comments (no X, respostas) ou both (padrão both)
postscommentsboth
periodstring
string
Janela de tempo (padrão week)
dayweekmonthyear
sortstring
string
new = mais novo primeiro (padrão); relevance = ordem de relevância de cada rede
newrelevance
languagestring
string
pt, en ou any (padrão any). Onde a rede não filtra, usa detecção simples do idioma do texto
Anúncios ativos sobre um tema nas bibliotecas públicas do Meta (Facebook e Instagram), TikTok e LinkedIn: texto, título, CTA, página de destino, formato, onde roda, há quantos dias está no ar e quantas variações tem. Ordena pelos sinais de anúncio vencedor (quem paga não mantém no ar o que não converte: 30+ dias ou 3+ variações = forte). Use para 'o que está em alta nos anúncios de X', pesquisa de criativos e ofertas.
Parâmetro
Tipo
Descrição
queryobrigatóriostring
string
Tema, produto ou palavra-chave, ex.: "curso de inglês", "skincare"
platformsstring[]
string[]
Padrão: meta
metatiktoklinkedin
countrystring
string
País ISO-3166 (BR, US...) ou ALL. Padrão BR (vale para Meta e LinkedIn)
Ver exemplo de resposta (structuredContent, encurtado)
json
{
"query": "curso de inglês",
"country": "BR",
"platforms": ["meta"],
"ads": [
{
"platform": "meta",
"url": "https://www.facebook.com/ads/library?id=688654197622766",
"advertiser": "Professor Kenny",
"active": true,
"started_at": "2025-10-06T07:00:00+00:00",
"days_running": 357,
"variations": 12,
"format": "video",
"headline": "Curso de Inglês Prof Kenny",
"text": "Vi que você quase iniciou o melhor curso de inglês do país...",
"cta": "Learn more",
"landing_url": "https://www.profkenny.com.br/...",
"placements": ["facebook", "instagram"],
"winner_signal": "forte"
}
],
"total_found": 27,
"library_totals": { "meta": 7840 },
"credits_charged": 4
}
advertiser_ads
Custa 8 créditos no Meta, 8 no Google pelo site ou id (12 pelo nome) e 4 no LinkedIn e no TikTok.
Todos os anúncios ativos de uma marca ou concorrente no Meta, Google (Pesquisa, YouTube, Display), LinkedIn e TikTok, com o resumo por rede: quantos anúncios, formatos e o mais antigo no ar. Aceita o nome da empresa, o site (ex.: reportei.com, o mais preciso) ou o id de uma página do Meta ou de um anunciante do Google. Cada rede devolve matched (a empresa consultada e como foi achada) e alternatives (outras com nome parecido): se não for a empresa certa, avise o usuário e chame de novo com o id da alternativa.
Parâmetro
Tipo
Descrição
advertiserobrigatóriostring
string
Site (ex.: opus.pro), nome da empresa/página ou id de uma alternativa devolvida antes
Criativo completo de um anúncio pelo link da biblioteca (Meta: facebook.com/ads/library?id=...; Google: adstransparency.google.com; LinkedIn: linkedin.com/ad-library; TikTok: library.tiktok.com): textos de todas as versões, CTA, destino, dias no ar e a transcrição do vídeo (Meta). Use para destrinchar gancho, roteiro e oferta.
Parâmetro
Tipo
Descrição
urlobrigatóriostring
string
Link do anúncio na biblioteca (ou o ID do anúncio do Meta)
Baixa o vídeo de um link (YouTube, TikTok sem marca d'água, Instagram, X, Facebook) e devolve um link de download. Use só para conteúdo próprio, licenciado ou para referência interna.
Custa 100 créditos + 4 por minuto de vídeo, limite de 180 min (estornados se falhar).
Transforma um vídeo longo em cortes verticais prontos para postar, com legenda, título, gancho e hashtags. Informe url OU job_id de um download já feito. Leva de 1 a 5 minutos: a tool devolve um job_id; consulte com get_job. Use em conteúdo próprio ou licenciado.
Parâmetro
Tipo
Descrição
urlstring
string
Link do vídeo
job_idstring
string
ID de um job de download concluído
clip_countinteger
integer
Quantos cortes (padrão 5)
Intervalo: 1 a 10
min_secondsinteger
integer
Duração mínima de cada corte (padrão 20)
Intervalo: 5 a 180
max_secondsinteger
integer
Duração máxima de cada corte (padrão 60)
Intervalo: 10 a 180
orientationstring
string
Formato de saída (padrão vertical 9:16)
verticalhorizontalsquareoriginal
captionsboolean
boolean
Queimar legendas palavra por palavra (padrão true)
languagestring
string
Idioma do áudio, ISO-639-1 (pt, en, es). Vazio = automático
Download e transcrição costumam voltar prontos na mesma chamada. Cortes levam de 1 a 5 minutos: a chamada devolve um job_id com status queued ou processing. Consulte get_job a cada 20 ou 30 segundos até o status virar completed (ou failed, com estorno automático dos créditos).
A API usa os mesmos créditos do painel e dos assistentes. A tabela abaixo sai da própria API, então está sempre com o preço vigente (a tool get_account devolve a mesma tabela). Planos em /pricing.
Custa 5 créditos por página de resultados consultada no Reddit e no YouTube e 10 por página no X; cobra só as páginas que responderam (o padrão, Reddit com posts e comentários e limit 25, custa de 10 a 25).
• Falhou? Não cobra: rede que não respondeu, post indisponível e job que falhou têm os créditos estornados.
• Limite de 120 chamadas por minuto por conta. Acima disso a resposta é HTTP 429; espere alguns segundos e tente de novo.
• Algumas chamadas buscam dados ao vivo em várias redes e levam até 60 segundos. Use timeout de 120 segundos no cliente.
Erros
Resposta
O que significa
HTTP 200 + result.isError: true
A ferramenta rodou e não conseguiu (créditos insuficientes, link inválido, post privado). A mensagem para mostrar ao usuário está em result.content[0].text.
HTTP 401 invalid_token
Chave ausente, errada ou trocada.
HTTP 429
Muitas chamadas por minuto.
HTTP 405
Use POST.
error.code -32700
O corpo não é um JSON válido.
error.code -32601
Método JSON-RPC não suportado.
error.code -32603
Erro interno. Tente de novo; se continuar, fale com o suporte.
exemplo: créditos insuficientes
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [{ "type": "text", "text": "Créditos insuficientes: esta tool custa 4 e restam 2. Faça upgrade em https://viralrecast.com/pricing" }],
"isError": true
}
}
Claude, ChatGPT e agentes
Como a API é um servidor MCP, ela entra direto no Claude, no ChatGPT, no Cursor e em qualquer agente compatível com MCP. O passo a passo de cada um está em /connect.
Crie a conta com Google, pegue a chave e faça a primeira chamada com os créditos grátis.
Use download e cortes só em conteúdo próprio ou licenciado. Veja os Termos de uso.
Problemas de conexão
Se o cliente MCP mostra "InvalidHTTPResponse", "Failed", "Error POSTing to endpoint" ou não conecta, mas a URL abre normal no navegador, o motivo mais comum é um antivírus com inspeção de HTTPS (Norton, Kaspersky, Avast, AVG, ESET, Bitdefender) ou um proxy corporativo. Ele abre o tráfego para inspecionar e devolve a resposta alterada, que o cliente não consegue ler.
• Adicione viralrecast.com às exceções da verificação de SSL/TLS (ou de HTTPS) do antivírus. No Norton: Segurança → Proteção do agente de inteligência artificial → Configurações → desligue "Monitoramento da web" (com ele, a "Varredura de servidores MCP").
• Reconecte o servidor MCP no cliente (no Claude Code: /mcp → viralrecast → Reconnect).
• Para confirmar: se o certificado de viralrecast.com no navegador aparece emitido pelo antivírus em vez de Let's Encrypt, é a inspeção de HTTPS.
• No claude.ai e no ChatGPT isso não acontece: a conexão sai da nuvem, não do seu computador.