Hermoso

Hermoso: MCP, CLI & Skills

O agente de marketing com IA com um gerador de anúncios com IA integrado, executado a partir de qualquer agente de IA: Claude Code, Claude.ai, Cursor, Codex, ou seus próprios scripts. Pesquise os anúncios que já estão vencendo em um mercado, gere anúncios de imagem e vídeo prontos (seu produto real inserido, com copy + CTA incluídos), publique-os em seus próprios canais sociais e crie e gerencie as campanhas de anúncios por trás deles, tudo por meio de ferramentas MCP, um CLI ou skills instaláveis do Claude.

906 ferramentas. tools/list é sempre o conjunto autoritativo; hermoso_capabilities (grátis) retorna o catálogo de modelos ao vivo com custos exatos de crédito por renderização, além do mapa completo de capacidades.

Uma extensão do Chrome também. Hermoso: salve e clone anúncios salva qualquer anúncio no seu swipefile com um clique, clona-o para sua marca e puxa os anúncios de qualquer empresa do seu site.

A maior parte não custa nada. Publicar e agendar posts, criar e gerenciar campanhas pagas, análises e insights, comentários e DMs, conectores, perfis e assentos de equipe são gratuitos em todos os planos, sem taxa por post ou por canal e sem preço por assento. Os créditos são gastos apenas na execução de um modelo de IA (imagem, vídeo, voz, texto, planejamento, pós-produção) e na pesquisa do Ad Spy, e publicar um anúncio que você já renderizou nunca é uma segunda cobrança. A única exceção é o X (Twitter), onde publicar e ler cobram alguns créditos por chamada porque o X cobra por solicitação de API.

Com o que ele se conecta. Plataformas de anúncios: Meta, Google Ads, TikTok Ads, LinkedIn Ads, Reddit Ads, X Ads, Pinterest Ads, Snapchat Ads, Microsoft Advertising, Apple Search Ads, ChatGPT Ads e AppLovin Ads, além de feeds de produtos no Google Merchant Center. Publicação e agendamento — onze canais: Facebook, Instagram, Threads, TikTok, YouTube, X, LinkedIn, Pinterest, Bluesky, Telegram e Google Business Profile. Mensagens: WhatsApp (você envia mensagem para uma pessoa, então não é um décimo segundo canal de publicação) e automações de DM no Instagram, Facebook Pages e Messenger, e X (um comentário por palavra-chave, um DM, uma resposta a story ou um link ig.me / m.me recebe uma resposta automática). Pesquisa de anúncios: as bibliotecas de anúncios do Meta, Google e LinkedIn, além de TikTok, Instagram, YouTube, Threads e Reddit orgânicos. Análises: Google Analytics 4, Google Search Console e os insights de posts e campanhas de cada plataforma conectada. Arquivos: Google Drive, Sheets, Docs e OneDrive.

Não é tudo ou nada. Pesquisa, criação, publicação/agendamento e gerenciamento de anúncios são quatro áreas independentes — nenhuma ferramenta exige que você tenha usado outra antes. Publique ou agende criativos que você já tem e não gere nada aqui (upload_file transforma qualquer arquivo local ou externo em uma URL que toda ferramenta de publicação, agendamento e construção de anúncios aceita); crie e leia campanhas nas suas próprias contas de anúncios com seus próprios criativos; pesquise concorrentes sem marca criada e sem canal conectado; ou gere um arquivo sem nada conectado e apenas baixe-o. Use a peça que você precisa, ou tudo junto.

Instale em um comando

Este repositório é um marketplace de plugins, uma extensão do Gemini CLI e um pacote de skills ao mesmo tempo, então um agente de codificação aceita o Hermoso em uma linha. Cada instalação traz as mesmas cinco skills (hermoso-research, hermoso-generate, hermoso-ad-from-brand, hermoso-product-photoshoot, hermoso-marketing), e as skills acionam o CLI hermoso por meio do npx. Nenhuma lista de ferramentas é carregada na sua sessão: um comando CLI não custa nada até ser executado, e ele alcança todas as ferramentas. Na primeira vez, seu agente executa npx -y hermoso auth login, que abre um navegador para fazer login.

Claude Code:

claude plugin marketplace add hermoso-ai/hermoso && claude plugin install hermoso@hermoso

Dentro de uma sessão, a mesma coisa é /plugin marketplace add hermoso-ai/hermoso e depois /plugin install hermoso@hermoso.

Codex CLI (ele lê o mesmo arquivo de marketplace):

codex plugin marketplace add hermoso-ai/hermoso && codex plugin add hermoso@hermoso

Gemini CLI:

gemini extensions install https://github.com/hermoso-ai/hermoso

Grok (xAI) vem em três formatos, e cada um se conecta de forma diferente:

• grok.com e os aplicativos Grok usam o conector hospedado: abra Plugins → Connectors → New Connector → Custom (ou vá direto para grok.com/connectors), cole https://app.hermoso.ai/mcp e faça login com sua conta Hermoso.

• Grok Bot: adicione o modelo Hermoso Marketing Bot. Ele chega conectado ao Hermoso e pede uma chave, que você cria no aplicativo em MCP & CLI → Terminal & API keys.

• Grok Build, o agente de terminal da xAI, executa um servidor MCP local. Faça login uma vez e depois adicione:

  npx -y hermoso auth login
  grok mcp add hermoso -- npx -y hermoso mcp
  

Cursor, OpenCode, GitHub Copilot, Windsurf e cerca de 75 outros agentes, por meio do instalador de skills aberto:

npx skills add hermoso-ai/hermoso

Ele pergunta em quais agentes instalar; -a opencode (ou cursor, github-copilot, windsurf) escolhe um, e --skill hermoso-research instala uma única skill. Os plugins de agente do VS Code também podem receber este repositório inteiro: execute Chat: Install Plugin From Source e cole https://github.com/hermoso-ai/hermoso.

ChatGPT e Claude.ai rodam em um navegador e não podem executar um CLI, então eles usam o conector hospedado (veja abaixo). O aplicativo de desktop do ChatGPT e os administradores do workspace do ChatGPT também podem ler o .claude-plugin/marketplace.json deste repositório, que instala as skills.

Sem navegador na máquina? Crie uma chave no aplicativo em MCP & CLI e execute npx -y hermoso auth login --token <key>.

Qual superfície seu agente deve usar?

Dois formatos, e o certo é decidido por o que seu cliente pode fazer, não pelo que preferimos.

Seu cliente	Use	Por quê
Roda em um navegador: Claude.ai, ChatGPT, Claude Desktop	o conector hospedado https://app.hermoso.ai/mcp	Ele não pode iniciar um processo local, então uma URL é a única forma que ele tem. Nada para instalar, nenhuma chave para colar, e o conjunto completo de ferramentas chega com o contexto da sua marca salvo. Esta é a resposta certa para esses clientes, não uma resposta inferior.
Pode executar um shell: Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, Hermes, seus próprios scripts	a instalação de um comando acima, ou o próprio CLI (npm install -g hermoso)	Um manifesto de ferramentas é carregado em cada sessão, quer uma ferramenta seja chamada ou não. Um comando de shell não custa nada até ser executado, e ele alcança todas as ferramentas, em vez da lista padrão.

O CLI responde às perguntas que um manifesto de ferramentas responderia, sob demanda e apenas quando perguntado:

npx -y hermoso tools --search reddit   # every matching tool, name + one line
npx -y hermoso tools plan_ad           # one tool's full argument schema
npx -y hermoso call plan_ad --json '{"product":"…"}'   # run it

tools e tools <name> leem um registro incluído no pacote (sem chave, sem rede, sem login), então um agente pode navegar por todo o produto antes que alguém faça login. Apenas call gasta, e só isso precisa de hermoso auth login uma vez.

Quer as ferramentas também na lista do seu agente de codificação? Esse é o servidor MCP, e é opcional. Um hermoso auth login cobre o CLI e permite que claude mcp add hermoso -- npx -y hermoso mcp pegue a chave sem bloco env, então o agente pode usar uma ferramenta nativa quando quiser resultados estruturados e usar o shell quando quiser amplitude. Isso custa contexto em cada sessão, então adicione quando uma sessão se concentrar em uma área e fizer muitas chamadas lá; enable_tools({groups:['ads']}) então ativa o gerenciamento de campanhas em uma única chamada gratuita.

Seu agente pode se cadastrar sozinho

Um agente sem conta Hermoso pode provisionar uma, obter sua própria chave e estar renderizando anúncios na mesma sessão. Sem humano no navegador, sem ticket, sem espera.

# 1. Start a signup. This call takes no credential, because the credential is what it creates.
curl -sX POST https://app.hermoso.ai/v1/signup \
  -H 'content-type: application/json' \
  -d '{"plan":"pro","period":"mo","email":"you@yourcompany.com"}'
# -> { "id": "cs_...", "checkout_url": "https://checkout.stripe.com/...", "claim_token": "hsc_...", "email": { "address": "you@yourcompany.com", "verified": false } }
# email = the human behind the account. A verification link goes there; the account works before it is clicked.
# It is a contact mailbox only, never a sign-in. GET /v1/account/email reports the state; POST /v1/account/email/resend re-sends or changes it.

# 2. Pay at checkout_url. Store claim_token first: it is returned only in that response.

# 3. Claim it. Poll until status is "ready".
curl -sX POST https://app.hermoso.ai/v1/signup/cs_.../claim \
  -H 'content-type: application/json' \
  -d '{"claim_token":"hsc_..."}'
# -> { "status": "ready", "api_key": "hmk_...", "credits": 3000 }

Essa chave hmk_ é a mesma credencial que tudo o mais nesta página aceita: /v1, o servidor MCP, o CLI. Aponte seu cliente para ela e toda a superfície está aberta.

Pagar é algo que um agente com capacidade de navegador já pode fazer sozinho. O checkout é a página hospedada do próprio Stripe, então o Claude no Chrome e clientes semelhantes concluem isso sem supervisão hoje. Todo o resto é uma transferência de um clique: envie checkout_url para quem tem o cartão. O mesmo formato cobre você mais tarde, quando estiver em execução: buy_credits e upgrade_plan geram um link pronto para pagamento para mais créditos ou um plano maior, e billing_status lê o saldo a qualquer momento.

Um agente com sua própria credencial de pagamento pode pagar sem nenhum humano. POST /api/billing/machine-payment com {"packId": "pack-1k"} responde ao HTTP 402 carregando um desafio WWW-Authenticate: Payment (Stripe, por meio do Machine Payments Protocol); pague o desafio e tente novamente, e o mesmo pacote de créditos cai no mesmo saldo. GET /api/billing/config lista os pacotes sob machinePayments. Mesmos pacotes, mesmos preços, sem cobrança por chamada.

O caminho agêntico exige um plano pago. Qualquer um deles. O plano gratuito existe para uma pessoa se cadastrar em app.hermoso.ai, e pedir isso aqui retorna uma recusa que diz isso. Nada é criado até que o pagamento seja concluído, então um cadastro não pago não deixa conta para trás e não cobra nada.

Uma coisa ainda quer uma pessoa, e vale a pena saber de antemão. Conectar uma conta social ou de anúncios significa uma tela de consentimento OAuth, e uma tela de consentimento não pode ser concluída sem cabeça em nenhuma plataforma. list_connectors mostra o que já está conectado e o que não está. Todo o resto roda sem navegador: pesquisa, geração, publicação em um canal já conectado, construção de campanhas, relatórios.

Formas completas de solicitação e resposta, além de todos os outros endpoints, estão no documento OpenAPI em app.hermoso.ai/openapi.json, servido ao vivo da mesma tabela que monta as rotas.

Instantâneo: o conector hospedado do Claude.ai

Cole https://app.hermoso.ai/mcp?src=readme no Claude → Customize → Connectors → Add → Add custom connector, pressione Continue, escolha Sign in now em Authentication (o detector do Claude pré-seleciona "No sign-in" porque nosso handshake de descoberta é aberto, e com isso sua primeira solicitação retorna "Authentication required"), pressione Add e Connect, aprove com sua conta Hermoso, e pronto: o conjunto completo de ferramentas com o contexto da sua marca salvo, cobrado no seu plano.

Início rápido para Claude Code (um comando)

1. Obtenha uma conta em app.hermoso.ai. O nível gratuito está incluído; planos e créditos são os mesmos que o Studio web usa. Ou pule o navegador completamente e deixe seu agente se cadastrar em um plano pago com POST /v1/signup (acima).
2. Instale o plugin. Ele adiciona as cinco skills do Hermoso, que acionam o CLI hermoso por meio do npx:

claude plugin marketplace add hermoso-ai/hermoso && claude plugin install hermoso@hermoso

Já está em uma sessão? /plugin marketplace add hermoso-ai/hermoso, depois /plugin install hermoso@hermoso. Codex, Gemini CLI e o resto estão em Instale em um comando. 3. Faça login uma vez. npx -y hermoso auth login abre seu navegador; seu agente também o executa sozinho na primeira vez que precisar do Hermoso. Em uma máquina sem navegador, use npx -y hermoso auth login --token hmk_… com uma chave da aba MCP & CLI, em Terminal & API keys (Settings → API keys, ou https://app.hermoso.ai/?tab=api-keys, vai direto para lá). 4. Peça o que quiser, em seus prompts normais. O Claude Code escolhe a skill do Hermoso para o trabalho e executa os comandos. Você não digita nenhum deles.

Prefere instalar o CLI manualmente? npm install -g hermoso coloca o mesmo comando hermoso no seu PATH, e as skills o usam quando ele está lá.

A URL hospedada também funciona no Claude Code, mas o plugin é o caminho mais leve lá porque não carrega lista de ferramentas nas suas sessões. Se você quiser o conector: claude mcp add --transport http hermoso "https://app.hermoso.ai/mcp?src=readme", e claude mcp list relata ! Needs authentication até você executar claude mcp login hermoso uma vez e aprovar no seu navegador (--no-browser imprime o link em uma máquina sem cabeça). Medido contra o Claude Code 2.1.282 em 2026-09-25.

Seu agente agora tem o estúdio completo com o contexto do seu perfil: os detalhes da marca, produtos, logotipos e memória aprendida que você configurou no aplicativo web se aplicam automaticamente (get_brand mostra o que está salvo; omita brand em plan_ad/plan_variations para usá-lo). As renderizações cobram seus créditos Hermoso, aos mesmos preços do Studio. Apenas execuções de modelo de IA e pesquisa do Ad Spy gastam créditos; publicação, agendamento, gerenciamento de anúncios e análises são gratuitos em todos os planos (publicar no X e ler dados do X são a única exceção por chamada; gerenciar anúncios do X é gratuito).

1. Servidor MCP (stdio), opcional em um agente de codificação

hermoso mcp executa um servidor MCP stdio expondo o conjunto completo de ferramentas, para um cliente que queira as ferramentas da Hermoso em sua própria lista. O pacote publicado hermoso dispensa clonagem: npx -y hermoso mcp o busca e o executa. Faça login uma vez com a CLI e nenhuma chave vai para qualquer configuração de cliente, porque hermoso mcp lê o bearer hermoso auth login armazenado:

npm install -g hermoso && hermoso auth login && claude mcp add hermoso -- npx -y hermoso mcp

Em uma máquina sem navegador, pule o login e passe a chave para o cliente:

claude mcp add hermoso -e HERMOSO_TOKEN=hmk_… -- npx -y hermoso mcp

Cursor / Codex: faça login da mesma forma e adicione ao mcp.json (o Codex usa o equivalente em TOML). Remova o bloco env completamente se você fez login acima; ele está lá para CI, onde o processo não consegue ler seu diretório pessoal:

{ "mcpServers": { "hermoso": { "command": "npx", "args": ["-y", "hermoso", "mcp"],
  "env": { "HERMOSO_API_BASE": "https://app.hermoso.ai", "HERMOSO_TOKEN": "<your token>" } } } }

Então pergunte ao seu agente: “Gere um anúncio em imagem com a Hermoso.”

O que as 906 ferramentas cobrem

Pesquisa de anúncios / spy — find_competitors, competitor_teardown, pull_competitor_ads, research_ads; as bibliotecas de anúncios do Meta / Google / LinkedIn (search_meta_ads, search_google_ads, search_linkedin_ads); redes sociais orgânicas (search_tiktok, search_instagram, search_youtube, search_reddit, search_threads); fetch_social_data, mine_angles, analyze_video, check_ad_policy, list_skills / get_skill.

Criar — draft_brand → plan_ad → render_ad (o pipeline de qualidade Studio: texto composto, fala limpa, música, cartão final da marca), ou generate_image / generate_video / generate_avatar (criadores UGC + sincronização labial). O elenco salvo do workspace é reutilizável: list_creators retorna cada criador salvo com o URL do retrato, save_creator adiciona um, delete_creator remove um — reenvie um retrato para generate_avatar / generate_video / recast_motion e a MESMA pessoa estrela em todos os anúncios, em vez de um novo rosto a cada renderização. Também make_template_ad (formatos de anúncio HTML nativos), make_explainer, product_sizzle, make_thumbnail, clone_static, recast_motion, reframe_video, upscale_video, dub_video, change_voice, finish_video, fix_beat, stitch_video, clip_video, post_edit, além de plan_variations + score_ad para distribuir e ranquear. A duração é sua para definir: passe durationSeconds para plan_ad e o storyboard é criado para ela — uma duração que cabe em um clipe do modelo de renderização é renderizada como uma única tomada contínua; durações maiores são costuradas a partir de atos (em um modelo de clipe de 15s, 40s = 15+15+10), nunca comprimidas no tempo. O que cabe em um clipe é o máximo do próprio modelo, não um número fixo: a maioria dos modelos de vídeo limita um clipe a 15 segundos, e o de clipe mais longo aceita 30 segundos em uma única tomada ininterrupta com áudio nativo sincronizado. hermoso_capabilities é a lista ao vivo — durações, resoluções e o custo exato em créditos de cada nível — e nomear esse modelo em model é como obtê-lo, já que uma renderização sem nome é roteada por um pool automático mais restrito.

Ads Studio (make_static_ads): escolha produtos e uma quantidade e receba um lote de anúncios estáticos prontos em uma única chamada, cada um com um ângulo de venda diferente e um layout diferente, com sua foto real do produto e logotipo aplicados. O catálogo de produtos do qual ele se baseia (list_products, add_product, refresh_products, update_product, remove_product) é um cache da página ao vivo de cada produto, então nomes, fotos e preços vêm da própria página.

Troque uma pessoa em qualquer vídeo (recast_hook, recast_motion): mantenha a cena, os cortes e o som e mude quem está na tela, usando sua própria foto, um criador salvo ou uma pessoa de IA (no Studio web você pode descrever um apresentador em palavras). Rostos reais de suas próprias fotos exigem um plano pago; pessoas de IA funcionam em todos os planos.

Playground de modelos brutos — o catálogo completo (30+ modelos de imagem / vídeo / voz / escrita, cada um com seu custo exato em créditos por renderização) sem enquadramento de anúncio: generate_image / generate_video com useBrand:false, generate_voice, generate_text. O padrão de imagem é o Nano Banana 2.1.

Publique em seus próprios canais — onze deles: Facebook, Instagram e Threads (post_to_meta), TikTok (post_to_tiktok), YouTube (post_to_youtube + update_youtube_video, youtube_video_insights, leitura/resposta de comentários), X (post_to_x, x_post_metrics, x_post_insights, x_mentions, list_x_dms, send_x_dm), perfil do LinkedIn e páginas da empresa (post_to_linkedin, post_to_linkedin_page), Pinterest (post_to_pinterest + quadros), Bluesky (post_to_bluesky, delete_bluesky_post, bluesky_post_metrics, além de list_bluesky_convos / read_bluesky_dm / send_bluesky_dm) e Telegram (post_to_telegram, delete_telegram_message, list_telegram_chats) e Google Business Profile (abaixo). schedule_post / list_scheduled / cancel_scheduled dão a você um calendário de conteúdo único exatamente para esse conjunto. upload_file traz qualquer mídia externa ou local, não apenas renderizações da Hermoso. Postar no X cobra créditos por chamada de API (o X cobra por solicitação); um post contendo um link custa 13× um sem. Google Business Profile é o painel que uma empresa mostra no Google Search e no Maps. post_to_google_business publica um Post com texto, opcionalmente uma foto, e um botão de call-to-action (o Google não aceita vídeo em Posts, então uma programação com apenas um vídeo é recusada para esse canal); list_google_business_posts e delete_google_business_post gerenciam o que está sendo exibido. list_google_business_reviews encontra as avaliações sem resposta ainda e reply_to_google_business_review responde uma como a empresa. google_business_insights relata impressões de pesquisa e Maps, chamadas, cliques no site e solicitações de rota, e google_business_search_keywords as palavras que as pessoas pesquisaram para encontrar o anúncio. list_business_locations, get_business_location e update_business_location leem e editam o próprio anúncio: horários, telefone, site, descrição, categorias. Perguntas e respostas do Business Profile não são oferecidas: o Google aposentou isso em 03/11/2025.

Mensagem para clientes no WhatsApp — mensagens, não um décimo segundo canal de publicação: você envia mensagem para uma pessoa, e nada aqui posta em um feed. list_whatsapp_accounts encontra a Conta Comercial e seus números, list_whatsapp_templates / create_whatsapp_template / delete_whatsapp_template gerenciam os modelos que o Meta revisa, e send_whatsapp_message envia um — com confirmação obrigatória, porque alcança um telefone real e o Meta cobra a empresa pela conversa. Dois limites que são fatos permanentes sobre a API do Meta, em vez de algo pendente: a Hermoso não recebe webhooks do WhatsApp, então não há histórico de mensagens para ler — ela não é uma superfície de caixa de entrada e list_inbox não a cobre — e fora da janela de 24 horas que se abre quando o cliente envia mensagem primeiro, o WhatsApp aceita um modelo APROVADO e nada mais.

Automatize DMs do Instagram — save_instagram_dm_automation configura uma regra que responde às pessoas pela marca: um comentário com uma palavra-chave em um post, no próximo post ou em qualquer post recebe uma resposta privada, e um DM, uma resposta a story ou um link ig.me recebe uma resposta, com botões de link opcionais, uma resposta pública a comentário, um bloqueio de seguidores e um teste. test_instagram_dm_automation mostra exatamente o que um comentário ou DM de exemplo enviaria sem enviá-lo, e list_instagram_dm_automations / delete_instagram_dm_automation leem as estatísticas e o log de envio de cada regra ou a removem. Cada pessoa recebe uma resposta por post, o Meta permite uma resposta privada dentro de 7 dias do comentário, e nenhuma IA roda no caminho de envio, então não custa créditos.

Automatize DMs no Facebook e no X também — save_dm_automation (com test_dm_automation, list_dm_automations e delete_dm_automation) aceita um channel: instagram, facebook (um comentário com palavra-chave em um post da Página ou um anúncio recebe uma resposta privada no Messenger; uma palavra-chave no Messenger ou um link m.me recebe uma resposta) ou x (uma menção com palavra-chave ou uma resposta sob seu post recebe uma resposta pública; uma palavra-chave em DM recebe um DM de volta). O X só permite um DM automatizado depois que a pessoa enviou um DM para você, e um DM dizendo STOP exclui essa pessoa. O Facebook é gratuito como o Instagram. O X nos cobra por chamada, então uma automação no X é cobrada em créditos por cada menção, resposta ou DM que o X entrega, além de cada resposta ou DM enviado, e ficar sem créditos interrompe suas regras no X.

Postagem automática (set_post_refill, get_post_refill, run_post_refill): diga com que frequência, onde e sobre o quê ("2 posts por dia no Instagram e no Bluesky sobre nossa rotina de manhã tranquila, deixe-me revisar primeiro") e a Hermoso cria novos posts a partir da sua marca e preenche seu calendário. Escolha revisar primeiro (cada lote espera sua aprovação, edição ou refazer) ou postar automaticamente (direto na programação, ainda removível). Ela segue as notas que você deixa e escreve a partir do que funcionou em cada canal. Créditos são usados apenas quando um post é feito.

Rode os anúncios — árvores de campanha completas, criadas pausadas e lidas de volta antes que qualquer coisa seja relatada, com cada mudança de gasto exigindo confirmação, em doze plataformas: Meta, Google Ads, LinkedIn Ads, Reddit Ads, Pinterest Ads, Microsoft Advertising, ChatGPT Ads (API de Anunciantes da OpenAI), X Ads, TikTok Ads, Snapchat Ads, Apple Ads (Apple Search Ads na App Store) e AppLovin Ads (relatórios e o pixel do site nas chaves que toda conta tem; construção de campanha quando a AppLovin habilitar o acesso à API de Gerenciamento de Campanhas na conta, e eventos de conversão no servidor com a chave da Conversion API que a AppLovin emite sob solicitação). Cada uma tem listar + relatar + criar + ferramentas de orçamento/status (por exemplo, list_google_ads_campaigns, google_ads_report, create_google_ads_campaign, set_google_ads_budget, set_google_ads_status). O Snapchat precisa de um passo extra que os outros não precisam: um anúncio aponta para um CRIATIVO, e cada criativo do Snapchat deve carregar um id de Perfil Público — construa-o com upload_snapchat_ads_creative.

Alimente as superfícies de compras — Google Merchant Center é o catálogo que uma campanha de Performance Max ou Shopping de varejo anuncia (create_google_ads_performance_max_campaign aceita um merchantCenterId), e você o gerencia daqui: contas e status de contas, fontes de dados, upsert / atualização / exclusão de produtos, inventário por região, cota, merchant_report para desempenho em nível de produto, notificações e fontes de conversão, além do loop de reprovação — list_merchant_issues diz o que está errado e merchant_issue_help retorna a correção documentada do próprio Google. Promoções exigem a inscrição do próprio comerciante no programa de promoções do Google; sem isso, o Google recusa essa sub-API diretamente. Microsoft Merchant Center é coberto no mesmo formato (lojas, catálogos, produtos, problemas) para o Bing Shopping.

Meça o que os anúncios alcançaram — o Google Analytics 4 fecha o ciclo. Cada outro conector aqui relata o que um anúncio custou; este é o que relata o que ele fez. analytics_report divide sessões, usuários, conversões e receita por canal, origem/mídia, campanha, página de destino, país, dispositivo ou data, para que a campanha que a Hermoso construiu e a receita que ela gerou fiquem em uma única conversa. analytics_realtime mostra quem está no site agora. Comece em list_analytics_properties — as ferramentas aceitam um id numérico de propriedade, não o Measurement ID G-XXXXXXXXX do seu snippet de rastreamento, e é isso que resolve um a partir do outro. Ele também escreve, além de ler: create_analytics_key_event marca um evento que o GA4 já coleta como um evento-chave — que é o que o torna importável no Google Ads como uma conversão — e create_analytics_custom_dimension registra um parâmetro de evento para que os relatórios possam dividir por ele, com list_analytics_definitions mostrando o que a propriedade já mede. Ele faz login com a mesma conta do Google que o Google Ads, YouTube e Drive, mas é uma conexão própria. Apenas GA4 — a API não tem superfície de Universal Analytics. Uma dimensão personalizada pode ser arquivada, mas nunca excluída, e uma propriedade comporta 50 delas com escopo de evento.

Arquivos — CRUD do Google Drive (save_to_drive, list_drive_files, update_drive_file, delete_drive_file, create_drive_folder), Google Sheets (create_sheet, append_to_sheet, read_sheet), Google Docs (create_doc, append_to_doc) e OneDrive (save_to_onedrive + CRUD completo). Workspace e conta — perfis (list_brands, create_brand, use_brand, update_brand, delete_brand; uma conta contém vários perfis, cada um sendo uma marca, um cliente, um criador ou um workspace pessoal, então uma agência opera todos os clientes por aqui), memória (remember, forget, list_memory), habilidades personalizadas (save_skill, get_skill, list_skills, delete_skill — a biblioteca única, que absorveu as antigas personas de AI-Employee), equipe (list_team, invite_member, remove_member, set_role), configurações (get_settings, update_settings — incluindo o idioma no qual cada anúncio, roteiro e plano é escrito), conectores (list_connectors, list_connector_accounts, set_connector_accounts, disconnect_connector), e cobrança (hermoso_credits, billing_status, buy_credits, upgrade_plan, set_auto_reload), além de list_jobs / get_job para renderizações assíncronas.

As contas de conector são selecionadas, não adivinhadas. Uma pessoa frequentemente administra várias Páginas do Facebook, clientes do Google Ads ou Páginas de empresa do LinkedIn. Somente as contas marcadas para um perfil são utilizáveis — aplicado no lado do servidor, e uma seleção vazia não compartilha nada. Vincular uma conta nova é a única etapa que não é headless (é uma tela de consentimento OAuth, então o usuário faz isso no aplicativo).

Os trabalhos de renderização ficam na fila no lado do servidor e são consultados até a conclusão, retornando uma URL servida.

2. CLI: o caminho sem contexto para agentes de terminal

bin/hermoso.mjs expõe o conjunto completo de ferramentas MCP como comandos de subprocesso, para que um agente possa executar comandos externos em vez de carregar um manifesto de ferramentas pesado.

npm install -g hermoso                             # installs `hermoso`
hermoso capabilities                               # valid model ids + costs (run first)
hermoso create --brand "YourBrand" --product "your best-selling product" --format image
hermoso generate image --prompt "…" --ref ./product.png --wait
hermoso generate video --prompt "…" --duration 8 --wait
hermoso competitors yourbrand.com
hermoso research "Liquid Death’s longest-running ads"

Adicione --json a qualquer comando para saída de máquina.

Esses atalhos são o caminho comum, não o limite. Toda ferramenta que o servidor MCP possui também é acessível aqui, incluindo os grupos de campanhas de anúncios e análises que um conector deixa de fora do seu conjunto padrão:

hermoso tools                          # every tool, grouped, name + one line
hermoso tools --group ads --search reddit   # narrow it
hermoso tools create_meta_campaign     # that tool's full argument schema
hermoso call create_meta_campaign --json '{"name":"…"}'   # run it
hermoso create_meta_campaign --name "…"                   # same thing, shorter

call passa pelo mesmo manipulador, a mesma validação de argumentos e os mesmos portões de confirmação/gastos que o servidor MCP usa, então não há uma segunda implementação que possa divergir. tools e tools <name> leem um registro incluído no pacote, então não precisam de chave, rede ou login.

3. Habilidades: o que um agente de codificação instala

skills/ contém cinco habilidades instaláveis:

Habilidade	O que ela faz
hermoso-research	Encontre concorrentes, puxe os anúncios reais em veiculação deles, destaque os ganchos que valem a pena copiar
hermoso-generate	Um prompt para uma imagem, vídeo, clipe de avatar ou corte costurado finalizado
hermoso-ad-from-brand	Uma marca ou domínio para um anúncio finalizado e alinhado à marca, com conceito e texto incluídos
hermoso-product-photoshoot	Uma foto real de produto composta em cenas de estúdio, estilo de vida ou herói
hermoso-marketing	O ciclo completo: pesquisa, criação, publicação e agendamento, campanhas pagas, medição

Elas são o que cada instalação de um comando no topo desta página adiciona, no Claude Code, Codex, Gemini CLI e através de npx skills add. A partir de um clone, copiar também funciona:

cp -r skills/* ~/.claude/skills/

Em seguida, invoque /hermoso-ad-from-brand an ad for yourbrand.com, our hero product.

Peça com suas próprias palavras

As habilidades se escolhem sozinhas. Estes são prompts completos, não comandos:

• Encontre meus 5 principais concorrentes para [produto + URL], puxe os melhores anúncios deles no Meta e TikTok dos últimos 90 dias e me diga os 3 ganchos e 2 formatos que valem a pena copiar, com as evidências.
• Crie os anúncios desta semana para [marca]: dois ganchos em dois formatos, um UGC e um visual de produto, 9:16. Avalie-os e faça a verificação de política antes de eu publicar.
• Aqui está um anúncio de concorrente: [link]. Analise por que ele funciona e reconstrua a estrutura com meu produto, minha marca e um gancho novo.
• Preencha minha fila social para os próximos 7 dias no Instagram, TikTok, X e LinkedIn, reaproveitando minha melhor postagem, com legendas por canal.
• Pegue o vencedor da semana passada e crie uma campanha de teste de $20/dia no Meta e TikTok, três conjuntos de anúncios, um ângulo cada. Deixe-a pausada e leia a árvore de volta para eu verificar.
• Puxe o desempenho da campanha do mês passado em todas as plataformas. Quais dois criativos venceram, por quê, e o que o briefing do próximo mês deveria dizer?

Configuração

Env	Significado
HERMOSO_API_BASE	A origem da API do Hermoso (padrão https://app.hermoso.ai — defina http://localhost:3000 se você executar o aplicativo você mesmo)
HERMOSO_TOKEN	Chave de agente Bearer (hmk_…) — obrigatória contra o aplicativo hospedado
HERMOSO_PROFILE	ID do perfil, para contas com vários perfis
HERMOSO_OWNER	Somente para um perfil que outra conta compartilhou com você (um workspace de equipe): o ID da conta proprietária. Defina-o junto com HERMOSO_PROFILE, e defina HERMOSO_PROFILE para o profileUuid desse workspace (um slug curto de perfil é recusado). Execute list_brands (ou hermoso list_brands pela CLI) para imprimir ambos os valores para cada workspace ao qual você pode entrar. O servidor reautoriza o par em cada solicitação, então um valor errado é recusado, nunca confiado.

mcp/http.mjs é o transporte de conector remoto hospedado (cole uma URL no Claude.ai → Conectores). Ele vem neste repositório para transparência e se recusa a montar sem identidade autenticada — sem gastos anônimos, nunca.

Licença

MIT © Hermoso