Conecte o Apple Search Ads ao Claude ou ao ChatGPT em cinco minutos

O conector Apple Search Ads da Hermoso liga a sua conta do Apple Ads ao Claude, ao ChatGPT, ao Cursor, à CLI ou a HTTP simples, para que um agente possa rodar seus anúncios de pesquisa na App Store por você. Ele monta a campanha, o grupo de anúncios, as palavras-chave de segmentação e as negativas, lê de volta o que a Apple de fato armazenou e informa o desempenho até o termo que alguém digitou antes de instalar. Tudo o que ele cria fica pausado, e ativar o gasto é uma etapa separada, que exige sua confirmação explícita. Os relatórios podem ir para uma planilha do Google, um painel do Looker Studio ou um arquivo JSON, e a página do MCP do Apple Ads lista tudo o que o conector faz.

Conectar leva cerca de cinco minutos. Você não vai rodar openssl, e nenhuma senha da Apple passa pela Hermoso.

Conecte o Apple Search Ads ao Claude

Para conectar o Apple Search Ads ao Claude, adicione a Hermoso ao Claude como um conector e, depois, conecte sua conta do Apple Ads dentro da Hermoso, uma vez. No Claude, abra Customize › Connectors › Add custom connector, dê o nome Hermoso, cole https://app.hermoso.ai/mcp e aprove com a sua conta Hermoso. Não há chave para colar no Claude. Depois, conecte o Apple Ads na Hermoso em Configurações › Conectores, seguindo os passos mais abaixo nesta página. A partir daí, o Claude pode chamar todas as ferramentas do Apple Ads que a Hermoso tem: peça um relatório, uma mudança de palavra-chave ou uma campanha nova com palavras simples. No Claude Code, são dois comandos: /plugin marketplace add hermoso-ai/hermoso e depois /plugin install hermoso@hermoso. Hermoso no Claude tem o passo a passo completo.

Conecte o Apple Search Ads ao ChatGPT

O ChatGPT funciona do mesmo jeito. No ChatGPT, abra Plugins, depois Add › Create MCP App, dê o nome Hermoso, cole https://app.hermoso.ai/mcp como Server URL, mantenha a Authentication em OAuth e aprove com a sua conta Hermoso. Se Create MCP App não aparecer, ative o modo desenvolvedor uma vez em Settings › Plugins › Developer mode. Com o Apple Ads conectado na Hermoso, o ChatGPT consegue puxar o seu relatório de palavras-chave, gravá-lo em uma planilha do Google ou rascunhar uma campanha para você conferir. Hermoso no ChatGPT mostra o caminho.

Cursor, Codex e qualquer outro cliente MCP

Qualquer cliente que fale o Model Context Protocol acessa as mesmas ferramentas no mesmo endereço. O Cursor lê https://app.hermoso.ai/mcp do seu mcp.json; o Codex usa o plugin da Hermoso com codex plugin marketplace add hermoso-ai/hermoso, que aciona as mesmas ferramentas pelo terminal. Qualquer que seja o cliente, as suas credenciais da Apple nunca passam pelo chat. O agente chama as ferramentas da Hermoso, e a Hermoso assina cada requisição enviada à Apple com a chave que ela guarda. A página do MCP do Apple Ads lista todas as ferramentas.

O que pedir depois de conectado

• “Traga o desempenho do Apple Search Ads da semana passada por palavra-chave e me mostre as dez com o maior custo por aquisição.”
• “Coloque o gasto, as instalações e o CPA dos últimos 30 dias por campanha em uma planilha nova do Google chamada Apple Ads.” (Conecte o Google Drive antes.)
• “Quais termos de pesquisa trouxeram instalações na minha campanha dos EUA neste mês e que eu ainda não estou dando lance como palavras-chave exatas?”
• “Adicione ‘budget planner’ e ‘expense tracker’ como palavras-chave de correspondência exata no grupo de anúncios Brand, e ‘jobs’ como negativa.”
• “Quais palavras-chave a Apple sugere para o meu app, e qual parcela das impressões eu tenho nas que já uso?”
• “Crie uma campanha pausada para o meu app no Reino Unido com orçamento diário de 50 dólares, e depois me mostre o que a Apple armazenou.”

Ler um relatório nunca mexe no gasto. Tudo o que o agente cria fica pausado, e a chave que liga o gasto espera a sua confirmação explícita.

Primeiro, o detalhe que trava a maioria das pessoas

As instruções da própria Apple dizem: “Na interface do Ads, escolha Account Settings › API. Cole a chave no campo Public Key.”

Esse campo não existe para um administrador de conta. Entre como administrador na sua conta, abra Account Settings › API, e o que aparece é uma tabela com o título Manage API Access (uma lista de provedores de serviço de terceiros com uma única ação, Remove Access) e nenhum campo de chave em lugar nenhum da página. Parece exatamente um recurso que não existe, e é por isso que as pessoas param aqui e concluem que a API não está disponível para elas.

Ela está disponível. O campo Public Key pertence a um usuário com uma função de API, e ser administrador da conta não é uma delas. O convite da Apple oferece seis funções, e exatamente duas são funções de API:

• API Account Manager: “acesso de leitura e escrita a todos os grupos de campanhas para gestão via API”. Esta é a que você deve escolher se quer que a Hermoso monte campanhas, e não apenas gere relatórios.
• API Account Read Only: “acesso somente de leitura a todos os grupos de campanhas para gestão via API”. Basta para relatórios, e nada além disso.

As outras quatro (Account Admin, Account Finance, Account Read Only e Limited Access) não conseguem gerar credenciais de API. Então a solução é um convite que você envia para si mesmo:

1. Abra Account Settings › User Management e escolha Invite Users.
2. Convide um endereço que você controla (o seu, ou um compartilhado como ads-api@yourcompany.com, para que a credencial sobreviva a qualquer pessoa) com a função API Account Manager.
3. Aceite o convite a partir dessa caixa de entrada e, depois, entre no Apple Ads como esse usuário.

Agora, Account Settings › API tem um campo Public Key.

A conexão, passo a passo

1. Comece na Hermoso. Configurações › Conectores › Apple Ads › Connect. A Hermoso gera uma chave de assinatura EC P-256 (a mesma chave prime256v1 que os dois comandos openssl da Apple produziriam) e mostra só a metade pública. Copie.
2. Entregue a metade pública à Apple. Como usuário com a função de API, abra Account Settings › API, cole no campo Public Key e clique em Save.
3. Copie de volta os três ids. A Apple agora mostra clientId, teamId e keyId acima desse campo. Os três.
4. Finalize na Hermoso. Cole os três ids e salve. A Hermoso troca um token com a Apple e lê a sua lista de organizações antes de guardar qualquer coisa, então um id digitado errado falha ali mesmo, enquanto você ainda consegue ver o que colou, e não na sua primeira consulta de relatório, uma hora depois.
5. Escolha a organização, se as suas credenciais cobrirem mais de uma. A conexão fica fixada na que você escolher.

Se algo der errado

Não há campo Public Key na página de API

Você está logado como Account Admin, ou com alguma das quatro funções que não são de API. Convide a si mesmo como API Account Manager e entre como esse usuário (veja acima). Este é o motivo mais comum de uma conexão do Apple Ads nunca ser feita.

A Apple rejeita as credenciais

Os três ids precisam pertencer à chave que a Apple está guardando. Copie de novo clientId, teamId e keyId logo acima do campo Public Key, e não de uma chave antiga que você substituiu. Se ainda falharem, comece a conexão de novo na Hermoso: isso gera um novo par de chaves, e você cola a nova metade pública na Apple.

A sessão de configuração expirou

A Hermoso guarda a chave privada gerada por 24 horas enquanto você vai colar a metade pública na Apple. Depois disso ela é descartada, de propósito. Comece a conexão de novo e cole a nova chave pública.

Eu já gerei uma chave com openssl

Então use ela. Cole a sua chave privada EC P-256 existente ao conectar, em vez de usar a da Hermoso, e a chave pública que já está na sua conta da Apple continua funcionando. Precisa ser uma chave EC P-256 (prime256v1). A Apple não aceita nenhuma outra curva.

Eu gerencio várias organizações do Apple Ads

Conecte cada uma em seu próprio perfil da Hermoso. Uma conexão fica fixada em uma única organização, o que impede que a campanha de uma agência caia na conta de outro cliente.

O que o conector do Apple Search Ads faz

Criar: create_apple_ads_campaign, create_apple_ads_ad_group, add_apple_ads_keywords, add_apple_ads_negative_keywords, update_apple_ads_object, set_apple_ads_status, delete_apple_ads_object.

Ler: list_apple_ads_campaigns (status, status de veiculação, orçamento diário e total, os países em que a campanha roda e o motivo declarado pela própria Apple quando ela não consegue rodar), list_apple_ads_ad_groups (lance padrão e se o Search Match da Apple está ativo), list_apple_ads_keywords (segmentação e negativas, com tipo de correspondência e lance), apple_ads_report (impressões, toques, instalações, gasto, TTR, CPT e CPA no nível de campanha, grupo de anúncios, palavra-chave, termo de pesquisa ou anúncio) e list_apple_ads_orgs.

Tudo isso pode ser chamado do Claude, do Claude Code, do Codex, do Cursor, do Cline, do OpenClaw, do Hermes ou de qualquer outro cliente MCP, e também do estúdio web. É o mesmo motor em todos os casos. Veja a visão geral do MCP ou a referência de ferramentas de anúncios.

E mais: cria criativos e anúncios (create_apple_ads_creative, create_apple_ads_ad), carrega até 1.000 palavras-chave em uma chamada (bulk_apple_ads_keywords) e lê os dados do próprio Apple: apple_ads_keyword_suggestions, apple_ads_impression_share, apple_ads_search_term_popularity e apple_ads_change_history. Todas elas podem ser chamadas do mesmo chat.

Exporte dados do Apple Search Ads

A mesma conexão gera relatórios. apple_ads_report puxa o desempenho de campanha, grupo de anúncios, anúncio, palavra-chave e termo de pesquisa (impressões, toques, instalações, gasto, taxa de toque, custo por toque e custo por aquisição), em totais ou em série horária, diária, semanal ou mensal, com até 5.000 linhas por página. Ler um relatório nunca mexe no gasto. Para onde as linhas vão depois é com você, e os três destinos mais comuns estão abaixo. O guia completo está em Exporte dados do Apple Search Ads.

Conecte o Apple Search Ads ao Google Sheets

Conecte o Google Drive ao lado do Apple Ads (uma única autorização do Google cobre Drive, Sheets e Docs) e peça ao seu agente que coloque o relatório em uma planilha. Ele chama apple_ads_report, depois create_sheet para criar uma planilha nova ou append_to_sheet para acrescentar as linhas desta semana em uma existente. O escopo do Google que a Hermoso pede é drive.file, que alcança apenas os arquivos que ela criou ou que você escolher. Passo a passo: Conecte o Apple Search Ads ao Google Sheets.

Exporte o Apple Search Ads para o Looker Studio

A Hermoso não tem conector nativo para o Looker Studio. O Looker Studio lê o Google Sheets com o conector próprio dele, então a planilha acima é a ponte: adicione-a uma vez como fonte de dados do Google Sheets, monte o painel, e cada acréscimo semanal aparece na próxima atualização. Power BI e Tableau leem a mesma planilha do mesmo jeito. Os passos do Looker Studio.

Exporte o Apple Search Ads para JSON

Para as linhas brutas, chame a ferramenta pela API REST da Hermoso com uma chave de API: POST https://app.hermoso.ai/v1/tools/apple_ads_report com os argumentos do relatório como corpo JSON, e leia as linhas em data.rows na resposta. Pelo terminal, npx -y hermoso call apple_ads_report --json '{...}' --structured imprime o mesmo resultado em JSON. Um exemplo completo de requisição.

Perguntas frequentes

Como conecto o Apple Search Ads ao Claude?

Adicione a Hermoso ao Claude como conector personalizado com a URL https://app.hermoso.ai/mcp e aprove com a sua conta Hermoso, depois conecte o Apple Ads na Hermoso em Configurações › Conectores. A partir daí, o Claude pode gerar relatórios, editar e criar as suas campanhas do Apple Search Ads pelas ferramentas do Apple Ads da Hermoso.

O ChatGPT consegue ler meus dados do Apple Search Ads?

Sim. Adicione https://app.hermoso.ai/mcp no ChatGPT em Plugins › Add › Create MCP App, e conecte o Apple Ads na Hermoso. Aí o ChatGPT pode puxar impressões, toques, instalações, gasto, TTR, CPT e CPA por campanha, grupo de anúncios, anúncio, palavra-chave ou termo de pesquisa, e gravar as linhas em uma planilha do Google.

Existe um servidor MCP do Apple Search Ads?

Existe. O servidor MCP hospedado da Hermoso, em https://app.hermoso.ai/mcp, expõe o conjunto completo de ferramentas do Apple Ads para o Claude, o ChatGPT, o Cursor, o Codex ou qualquer cliente MCP: relatórios, campanhas, grupos de anúncios, palavras-chave e negativas, criativos e anúncios, e as sugestões de palavras-chave da Apple. Tudo o que ele cria fica pausado.

Por que não há campo Public Key na página de API do Apple Ads?

Porque você está logado como Account Admin. A Apple só mostra esse campo para um usuário com uma função de API. Um administrador vê, no lugar, uma tabela “Manage API Access” com provedores de serviço de terceiros, sem nenhum campo de chave na página. Convide a si mesmo como API Account Manager em Account Settings › User Management, entre como esse usuário, e o campo aparece.

Qual função do Apple Ads eu preciso?

API Account Manager, se você quer que a Hermoso monte campanhas, grupos de anúncios e palavras-chave. A Apple descreve como “acesso de leitura e escrita a todos os grupos de campanhas para gestão via API”. API Account Read Only basta se você só quer relatórios. As outras quatro funções que a Apple oferece (Account Admin, Account Finance, Account Read Only e Limited Access) não conseguem gerar credenciais de API.

Preciso rodar openssl?

Não. As instruções da Apple entregam dois comandos openssl; a Hermoso gera o par de chaves EC P-256 para você e mostra só a metade pública. A metade privada é a que assina as suas requisições, e você nunca a vê, cola ou guarda. Se você já tem uma chave de outra ferramenta, pode trazê-la.

Conectar o Apple Ads custa alguma coisa ou arrisca gasto?

Não. As leituras podem ser chamadas à vontade, e todo objeto que a Hermoso cria é criado PAUSADO, sem exceção. Ativar um objeto é a única chave que libera gasto real, e ela exige confirmação explícita.

O que são clientId, teamId e keyId?

Os três identificadores que a Apple mostra acima do campo Public Key depois que você salva a sua chave. Eles identificam o seu usuário de API para a Apple; a chave privada prova que é você. Cole os três de volta na Hermoso e a conexão está pronta.

Uma conexão pode cobrir várias organizações do Apple Ads?

Uma conexão fica fixada na única organização que você escolhe ao criá-la. A Apple trata um orgId quase como um grupo de campanhas, então um mesmo login pode cobrir várias. Uma agência com um cliente por organização conecta cada uma em seu próprio perfil da Hermoso.

Preciso girar a chave a cada 180 dias?

Não. A Apple limita um segredo de cliente a 180 dias, e é por isso que as instruções dela pedem que você anote uma rotação. A Hermoso guarda a chave privada e gera um segredo novo e de vida curta para cada troca de token, então não há nada em arquivo de configuração para expirar.

Posso exportar dados do Apple Search Ads para o Google Sheets ou o Looker Studio?

Sim. Conecte o Google Drive ao lado do Apple Ads e o seu agente grava o relatório em uma planilha do Google com create_sheet ou append_to_sheet. A Hermoso não tem conector nativo para o Looker Studio; o Looker Studio lê essa planilha com o conector próprio do Google Sheets.

Posso obter os dados do Apple Search Ads em JSON?

Sim. Chame POST /v1/tools/apple_ads_report na API da Hermoso com uma chave de API e leia data.rows, ou rode hermoso call apple_ads_report com --structured pela CLI.