Hermoso

Hermoso — MCP, CLI & Skills

Execute toda a sua operação de marketing 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 finalizados (seu produto real composto, texto + 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, uma CLI ou skills instaláveis do Claude.

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

Com o que 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 e ChatGPT Ads, além de feeds de produtos no Google Merchant Center. Publicação e agendamento — dez canais: Facebook, Instagram, Threads, TikTok, YouTube, X, LinkedIn, Pinterest, Bluesky e Telegram. Mensageria: WhatsApp (você envia mensagem para uma pessoa, então não é um décimo primeiro canal de publicação). Pesquisa de anúncios: as bibliotecas de anúncios da Meta, Google e LinkedIn, além de TikTok, Instagram, YouTube, Threads e Reddit orgânicos. Analytics: 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 em suas próprias contas de anúncios com seus próprios criativos; pesquise concorrentes sem marca elaborada e sem canal conectado; ou gere um arquivo sem nada conectado e apenas baixe-o. Use a parte que você precisa, ou tudo junto.

Qual superfície seu agente deve usar?

Duas formas, e a correta é decidida pelo que seu cliente pode fazer, não pela 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 tem. Nada para instalar, nenhuma chave para colar, e o conjunto completo de ferramentas chega com seu contexto de marca salvo. Esta é a resposta certa para esses clientes, não uma inferior.
Pode executar um shell — Claude Code, Cursor, Codex, Cline, OpenClaw, Hermes, seus próprios scripts	a 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 do conjunto padrão.

A diferença medida (2026-08-27, contada como definições reais de ferramentas, em vez de estimada por bytes):

	ferramentas no alcance	carregadas por sessão
Conector hospedado, conjunto padrão	306	181.713 tokens
Conector hospedado, ?tools=all	718	472.062 tokens
Servidor stdio (npx -y hermoso mcp)	306	181.713 tokens
CLI	todas as 718	0

A CLI responde às mesmas perguntas sob demanda, e somente quando perguntada:

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

Então, um agente de terminal alcança sua primeira chamada em aproximadamente 3,4K tokens com todo o conjunto no alcance, contra 182K para uma fração dele. tools e tools <name> leem um registro incluído no pacote — sem chave, sem rede, sem login — para que um agente possa navegar por todo o produto antes que alguém faça login. Somente call gasta, e somente isso precisa de hermoso auth login uma vez.

Ambos ao mesmo tempo é aceitável, e é o que sugerimos para Claude Code. Um hermoso auth login cobre a CLI e permite que claude mcp add hermoso -- npx -y hermoso mcp pegue a chave sem bloco env, para que o agente possa alcançar uma ferramenta nativa quando quiser resultados estruturados e usar o shell quando quiser amplitude. Se você quiser apenas um, use a CLI: ela cobre estritamente mais.

Quando o conector ainda é a melhor troca em um cliente com capacidade de shell: uma sessão que fará muitas chamadas em uma área. enable_tools({groups:['ads']}) ativa o gerenciamento de campanhas em uma única chamada gratuita e as ferramentas então são nativas — sem aspas de shell, resultados estruturados. Uma ida e volta de shell supera carregar um grupo de 221K tokens para uma única ferramenta; o inverso é verdadeiro quando uma sessão se estabelece nessa área.

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. Nenhum humano em um navegador, nenhum ticket, nenhuma 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"}'
# -> { "id": "cs_...", "checkout_url": "https://checkout.stripe.com/...", "claim_token": "hsc_..." }

# 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, a 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 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 detém o cartão. A mesma forma cobre você mais tarde, quando estiver em operaçã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.

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 solicitá-lo 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 alguma e não cobra nada.

Uma coisa ainda exige uma pessoa, e vale 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 algum: 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 em Claude → Configurações → Conectores → Adicionar conector personalizado, aprove com sua conta Hermoso, pronto — o conjunto completo de ferramentas com seu contexto de marca salvo, cobrado no seu plano.

Início rápido para Claude Code (uma linha)

1. Obtenha uma conta em app.hermoso.ai — nível gratuito 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 sozinho em um plano pago com POST /v1/signup (acima).
2. Execute uma linha. Seu navegador abre uma vez para fazer login. Nada para colar, e nenhuma chave cai em .claude.json:

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

3. Peça o que você quer, em seus prompts normais. Claude Code alcança uma ferramenta, ou executa o comando hermoso no seu terminal, o que o trabalho precisar. Você não digita nenhum dos dois.

As ferramentas de campanha de anúncios e analytics ficam fora da lista de ferramentas até você ativá-las com enable_tools, o que mantém tudo enxuto. Em uma máquina sem navegador, faça login com hermoso auth login --token hmk_… usando uma chave de Configurações → Agentes & API, ou pule o login e passe a chave para o cliente:

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

A URL hospedada também funciona no Claude Code, mas é o caminho pior lá e vale saber por quê: claude mcp add --transport http hermoso https://app.hermoso.ai/mcp é aceito, e então claude mcp list relata ! Needs authentication porque o cliente não iniciará o fluxo OAuth sozinho — você precisa abrir uma sessão, executar /mcp, encontrar o servidor e pressionar Autenticar. Medido contra Claude Code 2.1.241 em 2026-08-23.

Seu agente agora tem o studio completo com o contexto do seu workspace: o perfil de 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 — mesmos preços do Studio.

1. Servidor MCP (stdio) — Claude Code / Cursor / Codex

hermoso mcp executa um servidor MCP stdio expondo o conjunto completo de ferramentas. O pacote hermoso publicado significa sem clone — npx -y hermoso mcp busca e executa. Faça login uma vez com a CLI e nenhuma chave vai para qualquer configuração de cliente, porque hermoso mcp lê o hermoso auth login de portador armazenado:

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

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

{ "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 de imagem com Hermoso."

O que as 718 ferramentas cobrem

Espionagem de anúncios / pesquisa — find_competitors, competitor_teardown, pull_competitor_ads, research_ads; as bibliotecas de anúncios da Meta / Google / LinkedIn (search_meta_ads, search_google_ads, search_linkedin_ads); social orgânico (search_tiktok, search_instagram, search_youtube, search_reddit, search_threads); fetch_social_data, mine_angles, analyze_video, check_ad_policy, list_skills / get_skill.

Criação — draft_brand → plan_ad → render_ad (o pipeline de qualidade do Studio: texto composto, fala limpa, música, cartão final de 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 sua URL de retrato, save_creator adiciona um, delete_creator remove um — repasse 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, remix_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 expandir e classificar. 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 renderiza como uma única tomada contínua, mais longa é costurada a partir de atos (em um modelo de clipe de 15s, 40s = 15+15+10), nunca comprimida 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 modelo de clipe mais longo aceita 30 segundos em uma única tomada ininterrupta com áudio sincronizado nativo. hermoso_capabilities é a lista ao vivo — durações, resoluções e o custo exato de crédito de cada nível — e nomear esse modelo em model é como você o obtém, já que uma renderização sem nome é roteada por um pool automático mais restrito.

Playground de modelos brutos — o catálogo completo (30+ modelos de imagem / vídeo / voz / escrita, cada um com seu custo exato de crédito por renderização) sem enquadramento de anúncio: generate_image / generate_video com useBrand:false, generate_voice, generate_text. Publique nos seus próprios canais — dez 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 + boards), 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). schedule_post / list_scheduled / cancel_scheduled dão a você um calendário de conteúdo exatamente para esse conjunto. upload_file traz qualquer mídia externa ou local, não apenas renderizações do Hermoso. Postagens no X cobram créditos por chamada de API (o X cobra por solicitação); um post com link custa 13× um sem. Retido, e nomeado em vez de oculto: Google Business Profile está construído (post_to_google_business, avaliações, Q&A, insights) e não é oferecido — o Google permite essa API por projeto e a nossa lê 0 QPM, então toda chamada retornaria 403 para cada usuário. Ele está no enum de canais do schedule_post e é recusado no enfileiramento.

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

Execute os anúncios — árvores completas de campanhas, criadas pausadas e lidas antes de qualquer relatório, com cada mudança de gasto com confirmação obrigatória, em onze 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 e Apple Ads (Apple Search Ads na App Store). Cada uma tem ferramentas de listar + relatar + criar + 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 uma etapa extra que os outros não precisam: um anúncio aponta para um CREATIVE, e todo creative do Snapchat deve conter um Public Profile id — 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 recebe 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 ciclo de desaprovaçã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 imediatamente. 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 — Google Analytics 4 fecha o ciclo. Todos os outros conectores aqui relatam 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 o 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 usam 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 evento-chave — que é o que o torna importável para o Google Ads como conversão — e create_analytics_custom_dimension registra um parâmetro de evento para que os relatórios possam detalhar por ele, com list_analytics_definitions mostrando o que a propriedade já mede. Ele faz login com a mesma conta do Google que Google Ads, YouTube e Drive, mas é uma conexão própria. Somente 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 — workspaces de marca (list_brands, create_brand, use_brand, update_brand, delete_brand — uma conta comporta muitas marcas, 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, script 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 conectores são escolhidas, não adivinhadas. Uma pessoa frequentemente administra várias páginas do Facebook, clientes do Google Ads ou páginas da empresa no LinkedIn. Somente as contas marcadas para uma marca são utilizáveis — aplicado no 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 a faz no aplicativo).

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

2. CLI — o caminho econômico em tokens para agentes de terminal

bin/hermoso.mjs expõe todo o conjunto de ferramentas do MCP como comandos de subprocesso, para que um agente possa chamar o shell 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 em 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 handler, a mesma validação de argumentos e os mesmos portões de confirmação/gasto que o servidor MCP usa — 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 do Claude — comandos de barra que envolvem a CLI

skills/ contém quatro habilidades instaláveis: hermoso-generate, hermoso-ad-from-brand, hermoso-product-photoshoot, hermoso-research.

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

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

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 workspace de marca, para contas com vários perfis de marca
HERMOSO_OWNER	Somente para uma marca 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 marca é 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 hospedado de conector remoto (cole uma URL no Claude.ai → Conectores). Ele vem neste repositório para transparência e se recusa a montar sem identidade autenticada — sem gasto anônimo, nunca.

Licença

MIT © Hermoso