ADM Google Ads MCP Server

Conecte o Claude Code, Codex, Cursor ou Windsurf às suas contas do Google Ads. Leia dados de campanha em linguagem simples e crie novas campanhas de Search com a ADM AI.

Ver em adm.ccExperimente este MCPPatrocinado

Servidor MCP hospedado

npx add-mcp 'https://app.adm.cc/mcp'

Instala no Claude Code, Codex, Cursor e outros

Documentação

A habilidade ADM Google Ads permite que uma ferramenta de IA de codificação leia suas contas do Google Ads e crie campanhas de Search a partir de um plano escrito. Ela funciona com Claude Code, Codex, Cursor e Windsurf. A habilidade é um único arquivo, SKILL.md, que descreve o fluxo de trabalho; o trabalho em si é executado por meio do servidor MCP da ADM, que conecta a ferramenta de IA às contas do Google Ads vinculadas à sua conta ADM.

Leitura em todos os planos: relatórios, termos de pesquisa, palavras-chave, anúncios e ativos estão disponíveis em todos os planos ADM, incluindo o Free.
Escrita em planos pagos: criar campanhas, grupos de anúncios, anúncios, palavras-chave, palavras-chave negativas e ativos exige um plano pago (Starter, Professional ou Enterprise).
ADM hospedado hoje: o servidor ADM hospedado atualmente oferece as ferramentas de leitura e rascunhos de IA. As ferramentas de escrita ainda não estão disponíveis lá; para criar uma campanha no Google Ads, use o assistente de campanhas na ADM.
Pré-visualização antes de cada alteração: a ADM valida cada alteração e retorna uma pré-visualização. Nada é gravado no Google Ads até que você aprove.
Novas campanhas são pausadas: toda campanha é criada pausada e só é ativada quando você solicitar em uma mensagem separada.

Endereços:

Arquivo da habilidade: https://adm.cc/docs/google-ads-skill/SKILL.md (nome da pasta adm-google-ads)
Servidor MCP: https://app.adm.cc/mcp (Streamable HTTP), autenticado com uma chave de API ADM enviada como Authorization: Bearer adm_xxx
Versão do contrato: 2026-10-03

1. Comece em três etapas

Etapa 1. Crie uma chave de API. Entre na ADM e abra https://app.adm.cc/apikeys. Escolha o nível de acesso:

Somente leitura: apenas relatórios e configuração. Funciona em todos os planos, incluindo o Free.
Leitura e escrita: relatórios mais as ferramentas de escrita. As ferramentas de escrita exigem um plano pago ativo.

A chave completa é mostrada uma única vez. Copie-a antes de fechar a caixa de diálogo.

Etapa 2. Peça à ferramenta de IA para instalar a ADM. Copie o prompt abaixo, substitua adm_xxx pela sua chave e envie-o à ferramenta de IA. A ferramenta de IA segue as etapas da seção 5 para conectar o servidor MCP da ADM, salvar o arquivo da habilidade e testar a conexão. Quando terminar, reinicie a ferramenta de IA se ela solicitar.

Install the ADM MCP server and the ADM Google Ads skill by following https://adm.cc/docs/google-ads-skill#ai-install. My ADM API key is adm_xxx

A chave permanece no histórico da conversa. Se esse histórico puder ser visto por outras pessoas, gire a chave na ADM (seção 10). Para configurar o servidor manualmente, veja a seção 4.

Etapa 3. Dê instruções em linguagem simples. Por exemplo: "Qual das minhas campanhas gastou mais nos últimos 30 dias?" ou "Crie as campanhas do plan.md." A seção 3 tem mais exemplos.

2. Quais ferramentas ADM a habilidade chama

O que você pede	Ferramentas ADM
Escolher ou alternar a conta do Google Ads	`get_accounts`
Relatórios e perguntas sobre desempenho	`get_campaigns`, `get_ad_groups`, `get_keywords`, `get_search_terms`, `get_ads`, `get_negative_keywords`, `find_negative_conflicts`, `get_paused_summary`, `get_assets`, `get_conversion_actions`, `get_customizers`
Ver desempenho por dispositivo (celular, computador, tablet)	`get_device_performance`
Reduzir ou excluir lances em celular, computador ou tablet	`set_device_bid_adjustments`
Ver quais locais gastaram e converteram	`get_location_performance`, `set_location_bid_adjustments`
Confirmar uma pré-visualização apenas com o id dela	`confirm_preview`
Criar campanhas a partir de um plano	`create_search_campaign`, `add_ad_groups`, `add_keywords`, `add_ads`
Palavras-chave negativas	`add_account_negative_keywords`, `create_shared_negative_list`, `attach_shared_negative_list`
Links de site, frases de destaque, snippets estruturados, preços, promoções e chamadas	`add_sitelinks`, `add_callouts`, `add_structured_snippets`, `add_prices`, `add_promotions`, `add_calls`
Nome da empresa	`add_business_name`
Ativos de imagem e logotipos da empresa	Endpoint de upload `POST https://app.adm.cc/mcp/uploads`, depois `add_images` ou `add_business_logo`
Grupos de anúncios rascunhados pela IA da ADM	`draft_ad_groups`, `get_ad_group_draft`
Uma nova campanha rascunhada pela IA da ADM	`draft_campaign`, `get_campaign_draft`, depois `create_search_campaign`
Verificar uma criação e retomar após uma interrupção	`get_campaign_setup`, `get_operation`
Ativar ou pausar uma campanha	`set_campaign_status`
Pausar uma campanha, ou alterar o nome, o orçamento diário, os lances ou os idiomas	`update_campaign`
Adicionar ou remover locais segmentados ou excluídos	`update_campaign_locations`
Criar, anexar ou alterar uma estratégia de lances compartilhada de portfólio	`get_bidding_strategies`, `create_bidding_strategy`, `attach_bidding_strategy`, `update_bidding_strategy`
Pausar ou desvincular um ativo	`set_asset_link_status`
Renomear, pausar, ativar ou alterar lances de um grupo de anúncios	`update_ad_group`, `set_ad_group_status`
Editar o texto de um anúncio existente	`update_ads`
Ativar, pausar ou remover anúncios ou palavras-chave	`set_ad_status`, `set_keyword_status`
Adicionar ou remover palavras-chave negativas	`add_campaign_negative_keywords`, `remove_negative_keywords`, `add_shared_negative_keywords`, `remove_shared_negative_keywords`
Marcar cliques com um parâmetro personalizado, modelo de rastreamento ou sufixo de URL final	`set_url_options`

A seção 6 descreve cada ferramenta e seus parâmetros.

3. O que você pode dizer após a configuração

"Qual das minhas campanhas gastou mais nos últimos 30 dias e quantas conversões cada uma obteve?"
"Liste os termos de pesquisa dos últimos 14 dias que custaram dinheiro sem conversão."
"Crie as campanhas do plan.md. Pré-visualize primeiro e aguarde minha aprovação."
"Rascunhe grupos de anúncios para a seção de aprimoramento de fotos do plan.md."
"Crie uma nova campanha de Search a partir de https://www.example.com/photo-enhancer. Explore as palavras-chave, depois pré-visualize e aguarde minha aprovação."
"Adicione banner.jpg como ativo de imagem à campanha photo-enhancer@DE."
"Alterne para a conta de anúncios MySecond."
"Marque cada campanha com o parâmetro personalizado myname para que eu possa ver de qual campanha veio um clique."

Conta padrão

Quando várias contas do Google Ads estão conectadas, a habilidade pergunta uma vez qual usar e salva a escolha em .adm/account.json no diretório do projeto (somente ID do cliente e nome da conta, nunca a chave de API). Solicitações posteriores no mesmo projeto usam essa conta, e cada operação nomeia a conta em que é executada. Quando apenas uma conta está conectada, a habilidade a usa sem perguntar. Para alterar a conta, diga "Alterne para a conta de anúncios MySecond". Se a conta salva for posteriormente desconectada na ADM, a habilidade para antes da próxima operação, informa que a conta salva não está mais conectada e pergunta qual conta usar, mesmo que apenas uma permaneça.

Exemplo: criar uma campanha a partir de um plano

Este exemplo usa uma marca fictícia, PixelUp, e cria uma campanha a partir de uma entrada de plano chamada photo-enhancer@DE: uma ferramenta online de aprimoramento de fotos anunciada na Alemanha em alemão.

A entrada do plano:

Campanha photo-enhancer@DE, local Alemanha, um grupo de anúncios photo-enhancer-DE
Página de destino https://www.example.com/de/photo-enhancer, caminho de exibição foto / verbessern
8 palavras-chave de correspondência de frase, 6 títulos, 2 descrições, 4 palavras-chave negativas de campanha
Configurações gerais: somente Pesquisa do Google, Maximizar cliques com limite de CPC, sem correspondência ampla

O plano não informa um orçamento diário nem o limite de CPC, então a ferramenta de IA pergunta ambos antes de criar qualquer coisa. O exemplo usa 10,00 por dia e um limite de 0,40 na moeda da conta.

O que perguntar:

Create the photo-enhancer@DE campaign from plan.md.
Daily budget 10.00, CPC cap 0.40. Preview first and wait for my approval.

A ferramenta de IA primeiro chama create_search_campaign sem confirm. A ADM valida a solicitação e retorna uma pré-visualização com todos os erros, a largura de exibição de cada texto, a moeda da conta e uma estimativa de orçamento mensal (orçamento diário × 30,4). A pré-visualização inclui um preview_id. Após sua aprovação, a ferramenta de IA envia os mesmos argumentos novamente com "confirm": true e esse preview_id.

{
  "customer_id": "123-456-7890",
  "campaign": {
    "name": "photo-enhancer@DE",
    "daily_budget": 10.00,
    "bidding": { "type": "MAXIMIZE_CLICKS", "max_cpc": 0.40 },
    "network_settings": { "google_search": true, "search_partners": false, "display_network": false },
    "geo_targets": [ { "country_code": "DE" } ],
    "negative_keywords": [ "\"kamera\"", "\"handy\"", "\"bildschirm\"", "\"monitor\"" ],
    "ad_groups": [
      {
        "name": "photo-enhancer-DE",
        "language": "de",
        "keywords": [
          "\"foto verbessern\"", "\"bildqualität verbessern\"", "\"foto schärfen\"", "\"bild vergrößern\"",
          "\"foto qualität verbessern online\"", "\"unscharfes foto scharf machen\"",
          "\"bild hochskalieren\"", "\"foto auflösung erhöhen\""
        ],
        "ads": [
          {
            "final_url": "https://www.example.com/de/photo-enhancer",
            "path1": "foto",
            "path2": "verbessern",
            "headlines": [
              { "text": "Fotoqualität verbessern" },
              { "text": "Bilder online vergrößern" },
              { "text": "Unscharfe Fotos schärfen" },
              { "text": "Fotos 2x oder 4x vergrößern" },
              { "text": "Ohne Installation nutzen" },
              { "text": "PixelUp Foto-Verbesserer" }
            ],
            "descriptions": [
              { "text": "Fotoqualität online verbessern: Bilder 2x oder 4x vergrößern und schärfen." },
              { "text": "Für Produktfotos, Social-Media-Beiträge und kleine Bilder. Direkt im Browser, ohne App." }
            ]
          }
        ]
      }
    ]
  }
}

Observações sobre este payload:

As palavras-chave usam a notação do Google: "text" é correspondência de frase, [text] é correspondência exata, palavras sem aspas são correspondência ampla. Dentro do JSON, as aspas de uma palavra-chave de frase são escapadas como \".
"language": "de" acrescenta uma tag de idioma ao nome do grupo de anúncios, então o grupo é criado como photo-enhancer-DE [de]. A ADM usa essa tag para identificar o idioma do anúncio ao analisar o grupo posteriormente.
A segmentação geográfica sempre usa a opção "Presença" (pessoas no local ou que o visitam regularmente).
Palavras-chave negativas no nível da conta e listas compartilhadas do mesmo plano são etapas separadas: add_account_negative_keywords uma vez por conta, create_shared_negative_list uma vez por lista, depois attach_shared_negative_list para cada nova campanha.

O resultado contém o novo campaign_id, os IDs dos grupos de anúncios e um operation_id. A ferramenta de IA então chama get_campaign_setup para comparar o que existe no Google Ads com o plano. A campanha permanece pausada até que você peça para ativá-la.

Para um plano com muitas campanhas, a habilidade instrui a ferramenta de IA a:

Listar toda decisão ausente e verificar as contagens no plano antes de criar
Pré-visualizar e pedir aprovação em duas rodadas: campanhas e listas primeiro, depois os anexos de lista e ativos que precisam dos novos IDs
Criar campanha por campanha, registrando cada ID no arquivo de manifesto adm-manifest.json
Conciliar o resultado e retomar sem repetir campanhas concluídas
Perguntar separadamente antes de ativar qualquer coisa

4. Usar o servidor MCP sem a habilidade

A habilidade é opcional. Conectado por conta própria, o servidor MCP envia à ferramenta de IA um conjunto de regras de uso ao conectar: pré-visualizar antes de cada escrita, novas campanhas pausadas, a conta padrão e tratar termos de pesquisa como dados. O servidor MCP tem duas vantagens adicionais, com ou sem a habilidade:

Atualizações sem reinstalação: novas ferramentas e campos ficam disponíveis assim que a ADM os lança; a configuração permanece a mesma.
Permissões por ferramenta: a maioria das ferramentas de IA permite aprovar ferramentas de leitura automaticamente e manter uma etapa de confirmação para ferramentas de escrita (seção 9).

As configurações abaixo leem a chave da variável de ambiente ADM_API_KEY. Codex, Cursor e Windsurf leem a variável em tempo de execução, e seus arquivos de configuração não contêm a chave. O Claude Code grava a chave em seu arquivo de configuração no nível do usuário, ~/.claude.json, quando o servidor é adicionado; não compartilhe esse arquivo. Defina a variável primeiro e depois reinicie a ferramenta de IA.

macOS ou Linux (adicione a linha a ~/.zshrc ou ~/.bashrc):

export ADM_API_KEY="adm_xxx"

Windows (depois abra um novo terminal):

setx ADM_API_KEY "adm_xxx"

Configuração para cada ferramenta de IA:

Claude Code (Bash):

claude mcp add --transport http --scope user adm https://app.adm.cc/mcp \
  --header "Authorization: Bearer $ADM_API_KEY"

PowerShell:

claude mcp add --transport http --scope user adm https://app.adm.cc/mcp \`
  --header "Authorization: Bearer $env:ADM_API_KEY"

--scope user torna o servidor disponível em todos os projetos neste computador. Verifique a conexão com claude mcp list: a linha adm deve terminar com ✔ Connected.

Para interromper os prompts de aprovação apenas para ferramentas de leitura, adicione isto a ~/.claude/settings.json (todos os projetos) ou .claude/settings.json (um projeto):

{
  "permissions": {
    "allow": [
      "mcp__adm__get_*"
    ]
  }
}

mcp__adm__get_* corresponde a toda ferramenta ADM cujo nome começa com get_: as nove ferramentas de leitura, mais get_ad_group_draft e get_campaign_draft, que apenas leem o estado de um rascunho de IA. Mantenha as ferramentas de escrita fora da lista de permissões (seção 9). draft_ad_groups e draft_campaign não alteram o Google Ads, mas cada chamada executa várias chamadas de IA, então a regra as deixa de fora também. Se você registrou o servidor com outro nome, substitua adm na regra por esse nome.

Codex:

codex mcp add adm --url https://app.adm.cc/mcp --bearer-token-env-var ADM_API_KEY

O Codex lê ADM_API_KEY quando inicia.

Cursor (~/.cursor/mcp.json para todos os projetos, ou .cursor/mcp.json em um projeto):

{
  "mcpServers": {
    "adm": {
      "url": "https://app.adm.cc/mcp",
      "headers": { "Authorization": "Bearer ${env:ADM_API_KEY}" }
    }
  }
}

Windsurf (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "adm": {
      "serverUrl": "https://app.adm.cc/mcp",
      "headers": { "Authorization": "Bearer ${env:ADM_API_KEY}" }
    }
  }
}

As entradas para Codex, Cursor e Windsurf seguem o formato de configuração MCP documentado de cada ferramenta. Reinicie a ferramenta de IA após alterar a configuração e peça para listar suas contas do Google Ads. No Windsurf, abra o arquivo das configurações de MCP com "View raw config" se ele não estiver no caminho acima. ${env:ADM_API_KEY} é lido do ambiente do próprio processo da ferramenta de IA. Cursor e Windsurf são baseados no VS Code e, quando abertos pelo Dock ou por um lançador de aplicativos, também carregam variáveis definidas em ~/.zshrc ou ~/.bashrc. Após definir ou alterar a variável, saia completamente da ferramenta de IA e abra-a novamente (no macOS, pressione Cmd+Q; fechar a janela não encerra o aplicativo); caso contrário, o cabeçalho é enviado sem a chave e o servidor retorna HTTP 401.

Solução de problemas de conexão

Sintoma	Causa	Correção
HTTP 401	A chave está ausente, digitada incorretamente ou tem espaços no início ou no fim	Verifique `ADM_API_KEY`, reinicie a ferramenta de IA ou remova o servidor e adicione-o novamente com a chave colada exatamente como mostrado
HTTP 401	A chave foi revogada na página de chaves de API	Crie uma nova chave e atualize a configuração (seção 10)
HTTP 401 no Windows	O cabeçalho usou uma variável do PowerShell entre aspas simples, então a variável não foi expandida	Use aspas duplas ou cole a chave diretamente no comando
HTTP 401 após definir a variável	A ferramenta de IA foi iniciada antes de a variável ser definida	Saia completamente da ferramenta de IA e abra-a novamente (no macOS, pressione Cmd+Q); inicie uma ferramenta baseada em terminal a partir de um novo terminal. Se o erro persistir, inicie o editor a partir de um terminal onde a variável está definida, por exemplo `cursor .`
HTTP 404	A URL está errada	A URL deve ser exatamente `https://app.adm.cc/mcp`: `https`, o subdomínio `app.` e o caminho `/mcp`
Tempo esgotado ou conexão recusada	Um proxy corporativo ou firewall bloqueia a solicitação	Defina `HTTPS_PROXY` antes de iniciar a ferramenta de IA ou peça ao administrador de rede para permitir `app.adm.cc`

Uma chave que funcionava antes e agora retorna 401 geralmente foi revogada. A página de chaves de API mostra quando cada chave foi usada pela última vez.

5. Etapas de instalação (para ferramentas de IA lerem)

Esta seção foi escrita para ferramentas de IA. Você só precisa concluir a etapa 2 da seção 1; a ferramenta de IA então segue as etapas abaixo por conta própria.

O usuário forneceu a você uma chave de API ADM (ela começa com adm_). Instale o ADM da seguinte forma e depois relate o que você fez.

Adicione o servidor MCP no nível do usuário, para que funcione em todos os projetos. Nome do servidor: adm. URL: https://app.adm.cc/mcp (Streamable HTTP). Cabeçalho: Authorization: Bearer <key>. Escreva a chave apenas na sua configuração MCP de nível de usuário, nunca em um arquivo de projeto ou repositório git. Se um servidor chamado adm já existir, substitua-o.

Ferramenta de IA	Como adicionar o servidor
Claude Code	Execute `claude mcp add --transport http --scope user adm https://app.adm.cc/mcp --header "Authorization: Bearer <key>"`
Codex	Em `~/.codex/config.toml`, adicione `[mcp_servers.adm]` com `url = "https://app.adm.cc/mcp"` e `http_headers = { "Authorization" = "Bearer <key>" }`
Cursor	Em `~/.cursor/mcp.json`, adicione `"adm": { "url": "https://app.adm.cc/mcp", "headers": { "Authorization": "Bearer <key>" } }` em `mcpServers`
Windsurf	Em `~/.codeium/windsurf/mcp_config.json`, adicione `"adm": { "serverUrl": "https://app.adm.cc/mcp", "headers": { "Authorization": "Bearer <key>" } }` em `mcpServers`

Mantenha quaisquer outros servidores já presentes no arquivo. No Windows, ~ é a pasta de perfil do usuário.

Salve a habilidade. Baixe https://adm.cc/docs/google-ads-skill/SKILL.md para adm-google-ads/SKILL.md dentro do diretório de habilidades que você leu para todos os projetos. O nome da pasta deve ser adm-google-ads. Crie diretórios ausentes. Se você não souber esse diretório, use o de nível de projeto:

Ferramenta de IA	Caminho do arquivo de habilidade
Claude Code	`~/.claude/skills/adm-google-ads/SKILL.md`
Codex	`.agents/skills/adm-google-ads/SKILL.md`
Cursor	`.cursor/skills/adm-google-ads/SKILL.md`
Windsurf	`.windsurf/skills/adm-google-ads/SKILL.md`

Teste a conexão. Chame get_accounts no servidor adm. Se a ferramenta não estiver disponível até você reiniciar, diga isso.
Relate ao usuário: onde a configuração do servidor e o arquivo de habilidade foram salvos, se uma reinicialização é necessária e as contas do Google Ads encontradas. Após uma reinicialização, o usuário pode dizer "Liste minhas contas do Google Ads" para verificar.

Atualizar a habilidade

O arquivo de habilidade tem uma versão em seu metadata. Quando ela está desatualizada, get_accounts retorna skill_update_hint e a ferramenta de IA informa você uma vez. Para atualizar, baixe https://adm.cc/docs/google-ads-skill/SKILL.md, substitua o adm-google-ads/SKILL.md local por ele (mesmo local da etapa 2 acima) e reinicie a ferramenta de IA.

6. Referência de ferramentas

Ferramentas que atuam em uma conta usam customer_id de get_accounts (formato 123-456-7890); get_operation, get_ad_group_draft e get_campaign_draft usam apenas seu próprio ID. Dinheiro está sempre na moeda da conta em unidades principais, por exemplo 5.00, nunca em micros. Janelas de relatório (days) são 7, 14 ou 30 dias completos no fuso horário da conta, excluindo hoje (padrão 7). Ferramentas de listagem retornam até limit linhas (1 a 200, padrão 50) e um next_cursor para a próxima página.

Ferramentas de leitura

Ferramenta	O que retorna	Parâmetros principais
`get_accounts`	Contas conectadas (customer_id, nome, moeda, fuso horário), seu plano, o escopo da chave, se gravações são permitidas, criações de campanha restantes neste mês e chamadas de gravação restantes hoje. Com `skill_version`, também informa se o arquivo de habilidade precisa de atualização (`skill_update_hint`). Chame-a primeiro.	`skill_version`
`get_campaigns`	Campanhas com configurações e desempenho, ordenadas por custo. Campanhas removidas nunca são retornadas.	`days`, `status` (ENABLED ou PAUSED), `limit`, `cursor`
`get_campaign_setup`	A configuração de uma campanha. `include` é qualquer um de `ad_groups`, `keywords`, `ads`, `assets` (padrão `ad_groups,keywords,ads`, sem ativos). Com `ad_groups`, os ativos da campanha permanecem na campanha e os ativos do grupo de anúncios permanecem em cada grupo de anúncios. `assets` sozinho retorna ambos, e as linhas do grupo de anúncios mantêm `level` e `ad_group_id`. Os anúncios incluem `ad_strength`. O `id` da palavra-chave é o ID do critério para `set_keyword_status`. `device_bid_adjustments` (apenas não zero; -100 exclui esse dispositivo) está na campanha e em cada grupo de anúncios.	`campaign_id`, `include`
`get_ads`	Anúncios de pesquisa responsivos com títulos, descrições, fixações, `performance_label` por ativo, força do anúncio e desempenho. `text_contains` corresponde a títulos e descrições. `compact` retorna apenas IDs e texto. `id` é o ID do anúncio para `update_ads` e `set_ad_status`.	`campaign_id`, `days`, `text_contains`, `compact`, `limit`, `cursor`
`get_keywords`	Palavras-chave em notação do Google com status, Índice de qualidade, CPC máximo e desempenho. Filtre com `status`, `match_type` e `text_contains`. `id` é o ID do critério para `set_keyword_status`.	`campaign_id`, `days`, `status`, `match_type`, `text_contains`, `limit`, `cursor`
`get_search_terms`	Consultas de pesquisa que acionaram seus anúncios, com a palavra-chave correspondida e desempenho. No máximo as 10.000 principais linhas por custo (`truncated` é verdadeiro quando limitado).	`campaign_id`, `days`, `limit`, `cursor`
`get_negative_keywords`	Palavras-chave negativas por nível: conta, campanha, grupo de anúncios e listas compartilhadas (com IDs de lista e campanhas anexadas). Cada `id` de palavra-chave é o ID do critério para `remove_negative_keywords`.	`campaign_id`
`get_assets`	Ativos de sitelink, chamada, snippet estruturado, preço, imagem, promoção, chamada telefônica, nome comercial e logotipo comercial. `level` é `customer`, `campaign` ou `ad_group` (omita para todos os três). Também `types`, `asset_ids`, `link_status`, `limit` e `cursor`. `asset_id` é o ID para `set_asset_link_status`.	`campaign_id`, `level`, `types`, `asset_ids`, `link_status`, `limit`, `cursor`
`get_bidding_strategies`	Estratégias de lances (compartilhadas) de portfólio: ID, nome, tipo, CPA ou ROAS desejado, teto de CPC e as campanhas em cada uma.	nenhum
`get_device_performance`	Desempenho dividido por dispositivo (MOBILE, DESKTOP, TABLET), incluindo taxa de conversão, custo por conversão e o ajuste de lance atual (0 = nenhum, -100 = excluído). Apenas campanhas de pesquisa. `level` é `campaign` (padrão) ou `ad_group`.	`level`, `campaign_id`, `days`, `limit`, `cursor`
`get_location_performance`	Desempenho dividido por onde o usuário estava. `granularity` é `country`, `region` (padrão) ou `city`. `bid_adjustment_percent` é definido quando esse local é segmentado e o lance não é 0. `location_id` pode ser passado para `update_campaign_locations` ou `set_location_bid_adjustments`.	`granularity`, `campaign_id`, `days`, `limit`, `cursor`
`get_ad_groups`	Grupos de anúncios com status, campanha, CPC máximo, lances, contagem de palavras-chave e contagem de anúncios.	`campaign_id`, `status`, `limit`, `cursor`
`get_paused_summary`	Quantas campanhas, grupos de anúncios, palavras-chave e anúncios estão pausados, com IDs e nomes (200 por nível).	nenhum
`find_negative_conflicts`	Palavras-chave positivas bloqueadas por uma negativa no nível de conta, lista compartilhada, campanha ou grupo de anúncios. `negatives` e `keywords` hipotéticos opcionais (até 50) são verificados antes de você adicioná-los.	`campaign_id`, `negatives`, `keywords`, `limit`, `cursor`
`get_conversion_actions`	Ações de conversão: nome, status, tipo, categoria, primária (conta na coluna Conversões), configurações de valor, contagem e atribuição. `include_metrics` adiciona os últimos 30 dias completos no fuso horário da conta, e a resposta inclui `date_range`.	`include_metrics`
`get_customizers`	Atributos de personalização de anúncios e seus valores no nível de conta, campanha e grupo de anúncios. Use `{CUSTOMIZER.Name:default}` no texto do anúncio; o limite de comprimento conta o padrão.	nenhum
`get_operation`	O resultado registrado de uma chamada de gravação: pendente, concluído, parcial, falhou ou desconhecido, e os recursos que foram criados.	`operation_id`

Ferramentas de gravação

Toda ferramenta de gravação faz uma prévia primeiro. Chamada sem confirm, ela valida e retorna uma prévia sem alterar nada. Cada prévia retorna um preview_id. Após a aprovação, chame confirm_preview com esse preview_id, ou chame a mesma ferramenta novamente com argumentos idênticos mais "confirm": true e esse preview_id. Uma chamada confirmada sem preview_id retorna invalid_argument. Um preview_id não confirmado com mais de 30 minutos retorna preview_required. Um preview_id que já foi confirmado retorna o resultado armazenado e não grava novamente, inclusive após esses 30 minutos. Para fazer a mesma alteração novamente, faça a prévia novamente e confirme com o novo preview_id após a aprovação.

Ferramenta	O que faz	Parâmetros principais
`create_search_campaign`	Cria uma campanha de Search completa em uma única chamada: orçamento, lances, redes, locais, palavras-chave negativas, listas compartilhadas, grupos de anúncios, palavras-chave e anúncios de pesquisa responsivos. Sempre criada pausada.	`campaign` (veja o exemplo na seção 3)
`add_ad_groups`	Adiciona grupos de anúncios com palavras-chave, negativas e anúncios a uma campanha de Search existente. Criados pausados, a menos que `status` esteja ENABLED.	`campaign_id`, `ad_groups`, `status`
`add_keywords`	Adiciona palavras-chave, palavras-chave pausadas e palavras-chave negativas do grupo de anúncios a um grupo de anúncios. Palavras-chave existentes são relatadas como `exists`.	`ad_group_id`, `keywords`, `paused_keywords`, `negative_keywords`
`add_ads`	Adiciona de 1 a 3 anúncios de pesquisa responsivos a um grupo de anúncios existente (mesmo formato de anúncio do `add_ad_groups`, incluindo `path1` e `path2`). Um grupo comporta no máximo 3, incluindo anúncios pausados. Um anúncio com os mesmos títulos e descrições de um anúncio existente é relatado como `exists`. Novos anúncios são ativados e veiculam após a revisão do Google quando o grupo e a campanha estão ativados.	`ad_group_id`, `ads`
`update_ads`	Edita anúncios de pesquisa responsivos no lugar. O ID do anúncio permanece. Até 20 anúncios, todos ou nenhum. `headlines` e `descriptions` substituem a lista inteira. `headline_replacements` e `description_replacements` (`{from, to}`) alteram um ativo pelo texto exato e mantêm seu pin; `to` vazio o exclui. Não combine uma substituição com a lista inteira no mesmo anúncio.	`ads`: `{ad_id, headlines?, headline_replacements?, descriptions?, description_replacements?, final_url?, path1?, path2?}`
`add_account_negative_keywords`	Adiciona negativas à lista no nível da conta, o que as bloqueia em todas as campanhas de Search, incluindo as em execução.	`keywords` (até 500)
`create_shared_negative_list`	Cria uma lista compartilhada de palavras-chave negativas e, opcionalmente, a anexa a campanhas na mesma solicitação.	`name`, `keywords` (até 1.000), `campaign_ids`
`attach_shared_negative_list`	Anexa uma lista compartilhada existente a campanhas.	`shared_list_id`, `campaign_ids`
`add_sitelinks`	Adiciona sitelinks: texto do link com até 25 caracteres, duas descrições opcionais com até 35 cada (ambas ou nenhuma), URL final.	`level`, `sitelinks`, `campaign_ids` ou `ad_group_ids`
`add_callouts`	Adiciona callouts, até 25 cada.	`level`, `callouts`, `campaign_ids` ou `ad_group_ids`
`add_structured_snippets`	Adiciona snippets estruturados. `header` deve ser um cabeçalho oficial para `language` quando você informa um (por exemplo, alemão `Marken`, dinamarquês `Typer`). Sem `language`, qualquer tradução oficial é aceita; um idioma desconhecido gera aviso e o Google verifica na confirmação. De 3 a 10 valores, até 25 cada.	`level`, `snippets` (`header`, `values`, `language`), `campaign_ids` ou `ad_group_ids`
`add_prices`	Adiciona ativos de preço com 3 a 8 ofertas. `language_code` deve ser um de: de, en, es, es-419, fr, it, ja, nl, pl, pt-BR, pt-PT, ru, sv. A moeda deve ser uma que o Google suporte para ativos de preço (USD, EUR, GBP e outras; não DKK ou NOK).	`level`, `prices`, `campaign_ids` ou `ad_group_ids`
`add_promotions`	Adiciona ativos de promoção. `promotion_target` tem no máximo 20 caracteres. Informe exatamente um de `percent_off` (`30` = 30% off) ou `money_amount_off` com `currency`, em unidades principais. `language_code` e `final_url` são obrigatórios. Opcionais: `occasion`, `discount_modifier` `UP_TO`, um de `promotion_code` ou `orders_over_amount` (também precisa de `currency`), e `start_date` / `end_date` (`yyyy-MM-dd`).	`level`, `promotions`, `campaign_ids` ou `ad_group_ids`
`add_calls`	Adiciona ativos de chamada: `country_code` (2 letras) e `phone_number`. `call_conversion_reporting_state` opcional; com `USE_RESOURCE_LEVEL_CALL_CONVERSION_ACTION`, um `call_conversion_action_id` opcional de `get_conversion_actions` (omitido = ação de conversão de chamada padrão do Google).	`level`, `calls`, `campaign_ids` ou `ad_group_ids`
`add_business_name`	Adiciona um ativo de nome de empresa, com no máximo 25 caracteres. A veiculação depende das verificações de elegibilidade do Google; a prévia as lista.	`level` (`customer` ou `campaign`), `business_name`, `campaign_ids`
`add_business_logo`	Adiciona um logotipo de empresa a partir de um arquivo enviado (veja Uploads de imagem abaixo): quadrado 1:1, pelo menos 128×128. A veiculação depende das verificações de elegibilidade do Google; a prévia as lista.	`level` (`customer` ou `campaign`), `logos` (`upload_id`, `name` opcional), `campaign_ids`
`add_images`	Adiciona ativos de imagem a campanhas de Search ou grupos de anúncios a partir de arquivos enviados (veja Uploads de imagem abaixo). Os resultados são por destino.	`level` (`campaign` ou `ad_group`), `images` (`upload_id`, `name` opcional), `campaign_ids` ou `ad_group_ids`
`set_campaign_status`	Pausa ou ativa até 50 campanhas. Informe `campaign_id` e `status`, ou `campaigns`. A prévia lista cada orçamento diário e a estimativa diária e mensal adicionada para campanhas que ainda não estão ativadas. Campanhas de CPC manual cujos grupos de anúncios ainda estão com um CPC máximo provisório (0,05 ou menos) geram aviso.	`campaign_id` e `status`, ou `campaigns`: `{campaign_id, status}`
`confirm_preview`	Executa uma prévia que o usuário aprovou. Informe apenas o `preview_id`. Os argumentos armazenados são reproduzidos, então o hash e o registro de idempotência são os mesmos da confirmação da ferramenta original.	`preview_id`
`set_location_bid_adjustments`	Define um ajuste de lance em um local que a campanha já segmenta. -90 a 900; 0 remove. Não adiciona nem remove locais. Lances inteligentes ignoram esses ajustes.	`items`: `{campaign_id, location_id, adjustment_percent}`
`set_customizer_values`	Cria um atributo de personalização de anúncio se necessário (TEXT, NUMBER, PRICE, PERCENT) e define seu valor no nível da conta, campanha ou grupo de anúncios.	`items`: `{name, type, value, level, campaign_id, ad_group_id}`
`update_campaign`	Em uma única alteração atômica: renomeia uma campanha, pausa-a e/ou define o orçamento diário, os lances ou os idiomas. `status` aceita apenas PAUSED. Um orçamento compartilhado é rejeitado. Informar `bidding` enquanto a campanha usa um portfólio a desanexa: a campanha faz lances por conta própria, e a prévia nomeia o portfólio que ela deixa. `bidding.max_cpc` é apenas o teto de Maximizar cliques; MANUAL_CPC o rejeita e os lances do grupo de anúncios são definidos com `update_ad_group`. Campanhas de Search não podem definir idiomas (o Google removeu isso em setembro de 2026); a prévia informa isso e não altera mais nada nessa chamada. A prévia de orçamento mostra o valor diário antigo e o novo e as estimativas mensais.	`campaign_id`, pelo menos um de `name`, `status` (PAUSED), `daily_budget`, `bidding`, `languages`
`update_campaign_locations`	Adiciona ou remove locais segmentados e locais excluídos em uma campanha, em uma única alteração atômica. Cada local é `{location_id}` de `get_campaign_setup` ou `get_location_performance`, ou `{country_code}`. Remover uma exclusão ou adicionar um alvo amplia a entrega e pode aumentar os gastos; a prévia informa isso quando a campanha está ENABLED. Remover o último local segmentado faz a campanha segmentar todos os locais, exceto as exclusões restantes. Alvos de raio não são suportados.	`campaign_id`, pelo menos um de `add_targets`, `remove_targets`, `add_exclusions`, `remove_exclusions`
`set_device_bid_adjustments`	Define ajustes de lance por dispositivo em campanhas de Search e grupos de anúncios (até 50), juntos ou nenhum. `device` é MOBILE, DESKTOP ou TABLET. `-100` exclui esse dispositivo. `-90` a `900` reduz ou aumenta o lance. `0` remove (um grupo de anúncios então herda a campanha). Um ajuste de grupo de anúncios substitui o da campanha. Maximizar conversões, ROAS desejado e Maximizar valor de conversão ignoram todos os valores, exceto `-100`. Em CPA desejado, o ajuste altera o CPA desejado desse dispositivo. Definir os três dispositivos como `-100` é rejeitado.	`items`: `{level, campaign_id, ad_group_id, device, adjustment_percent}`
`set_asset_link_status`	Pausa, ativa ou desvincula ativos (até 300). `REMOVED` desvincula e não pode ser desfeito; o ativo em si permanece. Um ativo vinculado a mais de um tipo de campo nesse nível é alterado em todos os vínculos. Um sitelink no nível da conta ainda pode aparecer em campanhas que já têm sitelinks; a prévia lista todas as campanhas que ele pode afetar. Outros tipos de ativo listam campanhas que não têm seu próprio ativo desse tipo. Os resultados são por vínculo.	`items`: `{level, asset_id, campaign_id, ad_group_id, status}`. `level` é `customer`, `campaign` ou `ad_group`. `status` é `ENABLED`, `PAUSED` ou `REMOVED`
`create_bidding_strategy`	Cria uma estratégia de lances de portfólio (`TARGET_CPA`, `TARGET_ROAS`, `MAXIMIZE_CLICKS`, `MAXIMIZE_CONVERSIONS`, `MAXIMIZE_CONVERSION_VALUE`). `MANUAL_CPC` é rejeitado. `max_cpc` é um teto de CPC opcional. `campaign_ids` opcional (até 50) anexa na mesma alteração atômica. Campanhas ENABLED iniciam um período de aprendizado.	`name`, `bidding`, `campaign_ids`
`attach_bidding_strategy`	Anexa campanhas a um portfólio existente (até 50). Substitui os lances próprios de cada campanha. Uma campanha em outro portfólio o deixa. Os resultados são por campanha.	`strategy_id`, `campaign_ids`
`update_bidding_strategy`	Renomeia um portfólio e/ou altera seu CPA desejado, ROAS desejado ou teto de CPC. O tipo não pode mudar. O novo alvo se aplica a todas as campanhas do portfólio; a prévia as lista.	`strategy_id`, pelo menos um de `name`, `bidding`
`update_ad_group`	Renomeia um grupo de anúncios, define-o como PAUSED ou ENABLED e/ou define `max_cpc`, em uma única alteração atômica. Não remove o grupo de anúncios. `max_cpc` é cobrado apenas quando a campanha usa MANUAL_CPC; a prévia informa isso caso contrário. Um grupo de anúncios ativado gasta assim que sua campanha é ativada.	`ad_group_id`, pelo menos um de `name`, `status` (ENABLED ou PAUSED), `max_cpc`
`set_ad_status`	Define anúncios como ENABLED, PAUSED ou REMOVED (até 100). REMOVED não pode ser desfeito. Um anúncio pausado ainda conta para os 3 anúncios de pesquisa responsivos que um grupo de anúncios pode ter. Não altera o status da campanha. Os resultados são por anúncio.	`ads`: `{ad_group_id, ad_id, status}`
`set_keyword_status`	Define palavras-chave positivas como ENABLED, PAUSED ou REMOVED (até 300). Palavras-chave negativas são recusadas. REMOVED não pode ser desfeito. Não altera o status da campanha. Os resultados são por palavra-chave.	`keywords`: `{ad_group_id, criterion_id, status}`
`set_ad_group_status`	Define grupos de anúncios como ENABLED, PAUSED ou REMOVED (até 50). REMOVED não pode ser desfeito. Não altera o status da campanha. Um grupo de anúncios ativado gasta apenas quando sua campanha já está ativada.	`ad_groups`: `{ad_group_id, status}`
`add_campaign_negative_keywords`	Adiciona palavras-chave negativas em uma campanha, na notação do Google (até 500). Elas se aplicam a todos os grupos de anúncios, incluindo os criados depois. Negativas existentes são `exists`.	`campaign_id`, `keywords`
`remove_negative_keywords`	Remove palavras-chave negativas (até 300). Apenas uma palavra-chave negativa é removida. Um critério de local é recusado (`update_campaign_locations`); um critério de idioma é recusado (`update_campaign`). REMOVED não pode ser desfeito.	`items`: `{level, parent_id, criterion_id}`. `level` é `account`, `campaign`, `ad_group` ou `shared_list`. Para `account`, `parent_id` pode ser omitido
`add_shared_negative_keywords`	Adiciona palavras-chave negativas a uma lista compartilhada existente (até 500). Não cria uma lista. A lista no nível da conta é recusada. A pré-visualização nomeia as campanhas às quais a lista já está anexada.	`shared_list_id`, `keywords`
`remove_shared_negative_keywords`	Remove palavras-chave de uma lista compartilhada existente pelo ID do critério (até 300). REMOVED não pode ser desfeito.	`shared_list_id`, `criterion_ids`
`set_url_options`	Define parâmetros personalizados, um modelo de rastreamento e um sufixo de URL final em campanhas, grupos de anúncios ou anúncios. Os parâmetros personalizados são mesclados por chave (um valor vazio remove essa chave). Um modelo de rastreamento definido aqui substitui o modelo no nível da conta para esse alvo. Não altera lances, orçamentos ou status.	`level` (`campaign`, `ad_group` ou `ad`), `targets` (até 20: `id`, `custom_parameters`, `tracking_template`, `final_url_suffix`)
`level` para ferramentas de assets é `customer` (todas as campanhas), `campaign` ou `ad_group`; `add_images` aceita apenas `campaign` e `ad_group`; `add_business_name` e `add_business_logo` aceitam apenas `customer` e `campaign`. `set_url_options` aceita `campaign`, `ad_group` ou `ad`. As ferramentas de assets aceitam até 20 itens e 20 alvos por chamada; assets adicionados a campanhas em execução começam a ser exibidos depois que o Google os revisa.

Rastreando de qual campanha veio um clique

Quando a conta do Google Ads já tem um modelo de rastreamento, defina um parâmetro personalizado em cada campanha, grupo de anúncios ou anúncio em vez de copiar esse modelo em todas as campanhas. Um modelo como {lpurl}?utm_campaign={_myname}&utm_term={keyword}&utm_ag={_groupname}&utm_ad={_adname} lê {_myname} da campanha. O nome do parâmetro que você armazena é myname (sem sublinhado); myname, _myname e {_myname} são a mesma chave. Defina _groupname no nível do grupo de anúncios e _adname no nível do anúncio da mesma forma.

{
  "customer_id": "123-456-7890",
  "level": "campaign",
  "targets": [
    { "id": 111, "custom_parameters": [{ "key": "myname", "value": "s-en-us" }] }
  ]
}

Outros parâmetros personalizados já existentes nessa campanha permanecem. Passe "value": "" para remover uma chave. Omita tracking_template e final_url_suffix para deixá-los; passe "" para limpar um. Definir um modelo de rastreamento aqui substitui o modelo no nível da conta para esse alvo, e a pré-visualização informa isso. Pré-visualize primeiro e depois confirme com preview_id. Verifique url_options com get_campaign_setup (os anúncios também o listam em get_ads). Uma chamada altera todos os alvos ou nenhum deles. Alterar opções de URL em um anúncio pode enviar esse anúncio de volta para revisão.

Rascunhos de grupos de anúncios com IA

draft_ad_groups cria rascunhos de grupos de anúncios para uma campanha de Pesquisa existente: a ADM analisa a página de destino, agrupa as palavras-chave por tema e gera anúncios de pesquisa responsivos para cada grupo. Isso não altera nada no Google Ads e exige uma chave de leitura e gravação e um plano pago. O rascunho é executado em segundo plano, então a chamada retorna um draft_id imediatamente.

Ferramenta	O que faz	Parâmetros principais
`draft_ad_groups`	Inicia um rascunho e retorna `draft_id`, `status` e `poll_after_seconds`.	`campaign_id`, `landing_page_url`, `keywords` (1 a 200), `language`, `paused_keywords`, `group_name_prefix` (até 100 caracteres), `ads_per_group` (1 a 3, padrão 1)
`get_ad_group_draft`	O estado de um rascunho: `pending`, `running`, `done` ou `failed`. Quando concluído: `ad_groups`, `primary_ad_group` e `warnings`. Quando falhou: `error`.	`draft_id`

Como um rascunho é usado:

Chame draft_ad_groups e depois chame get_ad_group_draft a cada poll_after_seconds até que status seja done ou failed. Um rascunho geralmente termina em 1 a 3 minutos.
Passe ad_groups exatamente como está para add_ad_groups e pré-visualize. Se add_ad_groups não estiver disponível ou can_write for falso, o rascunho é o resultado final: apresente os grupos de anúncios ao usuário. Os nomes dos grupos carregam o prefixo e a tag de idioma.
primary_ad_group nomeia o grupo com mais palavras-chave. Ele também recebe as palavras-chave pausadas, qualquer palavra-chave não atribuída pelo rascunho e as palavras-chave de grupos extras quando o rascunho contém mais de 20 grupos. Adicione anúncios escritos manualmente (add_ads) e palavras-chave negativas do grupo de anúncios (add_keywords) apenas a esse grupo.

Os rascunhos são mantidos por 24 horas. Cada rascunho executa várias chamadas de IA; o limite é de 60 rascunhos por hora por conta ADM, compartilhado com draft_campaign. Não repita uma chamada para a mesma entrada enquanto o rascunho estiver pendente ou em execução.

Rascunhos de IA de uma nova campanha

draft_campaign cria um rascunho de uma nova campanha de Pesquisa a partir de uma página de destino. A ADM lê a página, explora palavras-chave ou usa as que você passar, agrupa-as por tema e escreve anúncios de pesquisa responsivos para cada grupo. Isso não altera nada no Google Ads. Quando o rascunho estiver concluído, passe campaign exatamente como está para create_search_campaign (pré-visualize primeiro). Exige uma chave de leitura e gravação e um plano pago, e compartilha o limite horário de rascunhos com draft_ad_groups. Criar a campanha ainda usa a cota mensal de campanhas, que é verificada novamente por create_search_campaign.

Ferramenta	O que faz	Parâmetros principais
`draft_campaign`	Inicia um rascunho e retorna `draft_id`, `status`, `poll_after_seconds` e `explore_keywords`.	`landing_page_url`. Opcional: `keywords` (0 a 200; omita para explorar), `explore_keywords` (padrão falso quando palavras-chave são definidas; ignorado quando são omitidas), `language` (padrão `en`), `country_code` (padrão `US`), `daily_budget`, `bidding` (padrão `MAXIMIZE_CONVERSIONS`), `campaign_name`, `business_goal` (`SALES`, `LEADS` ou `TRAFFIC`, padrão `SALES`; apenas orienta a IA), `ads_per_group` (1 a 3, padrão 1)
`get_campaign_draft`	O estado de um rascunho: `pending`, `running`, `done` ou `failed`. Quando concluído: `campaign`, `missing_fields`, `warnings` e `strategy_notes`. Quando falhou: `error`.	`draft_id`

Como um rascunho de nova campanha é usado:

Chame draft_campaign. Omita keywords para deixar a ADM explorar palavras-chave da página de destino. Passe keywords para usar apenas essas palavras-chave, ou também defina explore_keywords como verdadeiro para mantê-las e deixar a ADM adicionar mais. Depois chame get_campaign_draft a cada poll_after_seconds até que status seja done ou failed. Um rascunho geralmente termina em 1 a 3 minutos. Não inicie outro rascunho para a mesma entrada enquanto um estiver pendente ou em execução.
Em failed, relate error e inicie um novo rascunho apenas se o usuário concordar. Em done, mostre ao usuário o nome da campanha, os grupos de anúncios e quaisquer warnings e strategy_notes.
Se missing_fields não estiver vazio, pergunte ao usuário sobre cada um antes de criar a campanha. campaign.daily_budget fica vazio quando você não passou daily_budget; não invente um orçamento. Defina o valor em campaign depois que o usuário responder.
Passe campaign exatamente como está para create_search_campaign e pré-visualize. Se create_search_campaign não estiver disponível ou can_write for falso, o rascunho é o resultado final: apresente o plano ao usuário, que pode criar a campanha no aplicativo web da ADM. O rascunho já segmenta apenas a Pesquisa do Google, com o país de country_code (padrão US) e o lance que você passou (padrão Maximizar conversões). Confirme com preview_id depois que o usuário aprovar. A nova campanha permanece pausada.
Verifique com get_campaign_setup.

Os rascunhos são mantidos por 24 horas. Um id de rascunho de draft_ad_groups não é visível para get_campaign_draft, e o inverso também é verdadeiro.

Uploads de imagens

add_images vincula imagens que foram enviadas primeiro para a ADM. Envie cada arquivo como multipart/form-data no campo file, com a mesma chave de API:

curl -F [email protected] -H "Authorization: Bearer adm_xxx" https://app.adm.cc/mcp/uploads

No PowerShell, use curl.exe com os mesmos argumentos.

O upload aceita arquivos JPG e PNG de até 5120 KB; o formato é detectado pelo conteúdo do arquivo, não pelo nome. A pré-visualização add_images então verifica as dimensões: quadrado 1:1 com pelo menos 300×300, ou paisagem 1.91:1 com pelo menos 600×314, com tolerância de 1% na proporção. Uploads exigem uma chave de leitura e gravação e um plano pago, e cada upload conta como uma chamada de gravação.

Resposta (HTTP 200):

{
  "upload_id": "upl_...",
  "width": 1200,
  "height": 628,
  "bytes": 184320,
  "sha256": "...",
  "content_type": "image/jpeg",
  "expires_at": "2026-10-01T09:30:00+00:00"
}

Um upload_id é válido por 24 horas (expires_at) e apenas para a conta ADM que o enviou. Depois que expira, add_images retorna not_found: envie o arquivo novamente e pré-visualize novamente com o novo upload_id.

Erros retornam {"error": {...}} com code, message, field_path, fix e request_id:

Status HTTP	`code`	Causa
400	`invalid_argument`	A solicitação não é `multipart/form-data`, o campo `file` está ausente ou o arquivo está vazio
401	`unauthorized`	A chave de API está ausente ou inválida
403	`permission_denied`	A chave é somente leitura, ou o plano não inclui acesso de gravação
404	nenhum	URL errada (o endpoint é `POST https://app.adm.cc/mcp/uploads` no subdomínio `app.`), ou uploads ainda não estão disponíveis na ADM hospedada
413	`invalid_argument`	O arquivo é maior que 5120 KB
415	`invalid_argument`	O arquivo não é uma imagem JPG ou PNG
429	`quota_exceeded`	Limite diário de segurança atingido (UTC)

O Google mostra assets de imagem apenas para contas elegíveis, por exemplo contas abertas há pelo menos 60 dias, com gastos recentes em Pesquisa e bom histórico de políticas, e que não estão em um vertical sensível. Para outras contas, o Google pode rejeitar o link, ou as imagens podem não ser exibidas. O Google também deduplica imagens por conteúdo: uma imagem idêntica já na conta é reutilizada, e uma já vinculada ao alvo é relatada como exists.

Limites de validação

Item	Limite
Grupos de anúncios por chamada	20
Anúncios por grupo de anúncios	3
Palavras-chave	300 por grupo de anúncios, 2.000 por chamada; cada uma com até 80 caracteres e 10 palavras
Palavras-chave negativas	1.000 por lista ou campanha
Locais	50 por campanha; cada um é `country_code` (ISO 3166-1 alpha-2) ou `location_id`; pelo menos um deve ser um alvo positivo
Listas compartilhadas por chamada `create_search_campaign`	20
Títulos	3 a 15 por anúncio, largura de exibição até 30
Descrições	2 a 4 por anúncio, largura de exibição até 90
Caminho de exibição	`path1` e `path2`, largura de exibição até 15 cada
Nomes	até 255 caracteres
Imagens	JPG ou PNG até 5120 KB; 1:1 com pelo menos 300×300 ou 1.91:1 com pelo menos 600×314 (tolerância de 1%)
Rascunhos de IA	0 a 200 palavras-chave por rascunho (um rascunho de nova campanha pode omitir palavras-chave), 1 a 3 anúncios por grupo

A largura de exibição conta caracteres CJK como 2. Emojis são rejeitados. Pins usam valores pinned_field de HEADLINE_1 a HEADLINE_3, DESCRIPTION_1 e DESCRIPTION_2.

O lance type é um de MANUAL_CPC, MAXIMIZE_CLICKS, MAXIMIZE_CONVERSIONS, MAXIMIZE_CONVERSION_VALUE, TARGET_CPA e TARGET_ROAS. MANUAL_CPC exige max_cpc na campanha ou em cada grupo de anúncios; com MAXIMIZE_CLICKS, max_cpc é o limite de CPC. network_settings.google_search deve ser verdadeiro.

campaign.languages é aceito, mas não aplicado: campanhas de Pesquisa são criadas sem segmentação por idioma no nível da campanha. Use o campo language do grupo de anúncios para registrar o idioma do anúncio.

7. Códigos de erro

Erros retornam uma estrutura:

{
  "code": "invalid_argument",
  "message": "What went wrong",
  "field_path": "campaign.ad_groups[0].ads[0].headlines[3].text",
  "fix": "How to correct it",
  "retryable": false,
  "retry_after_seconds": null,
  "action_url": null,
  "request_id": "..."
}

Código	Significado	O que fazer
`invalid_argument`	Um campo está ausente, fora do intervalo ou muito longo	Corrija todos os campos listados em `field_path` e visualize novamente
`account_not_found`	O customer_id não está conectado à sua conta ADM	Use um customer_id de `get_accounts`, ou conecte a conta no ADM
`not_found`	A campanha, o grupo de anúncios, a lista ou a operação não existe	Consulte o ID novamente com uma ferramenta de leitura
`permission_denied`	A chave é somente leitura, ou o plano não inclui acesso de escrita	Crie uma chave de leitura e escrita, ou faça upgrade do plano (`action_url`)
`quota_exceeded`	Não há mais criações de campanha este mês no seu plano, ou um limite diário de segurança foi atingido	Faça upgrade do plano (criações mensais) ou aguarde a redefinição indicada no erro
`preview_required`	`confirm: true` ou `confirm_preview` usou um `preview_id` que nunca foi confirmado e não possui visualização armazenada dos últimos 30 minutos	Visualize novamente, obtenha aprovação e confirme com o novo `preview_id`. Se este `preview_id` já foi confirmado, chame `confirm_preview` novamente; isso retorna o resultado armazenado
`conflict`	Um recurso com o mesmo nome, mas conteúdo diferente, já existe	Verifique o recurso existente; não renomeie e recrie
`busy`	Outra escrita nesta conta do Google Ads está em execução	Aguarde `retry_after_seconds` e tente novamente
`reauth_required`	A autorização do Google para o ADM expirou	Reconecte o Google Ads no ADM (`action_url`)
`google_ads_error`	O Google Ads rejeitou a alteração (política ou validação)	Leia o motivo do Google em `message` e ajuste
`result_unknown`	A chamada expirou ou foi interrompida e o resultado é desconhecido	Chame `get_operation` ou `get_campaign_setup` primeiro; se a alteração estiver ausente, visualize novamente e confirme com o novo `preview_id` após a aprovação
`internal`	Erro de servidor	Tente novamente uma vez; entre em contato com o suporte com `request_id` se repetir

HTTP 401 (unauthorized) é retornado antes de qualquer ferramenta ser executada quando a chave está ausente ou inválida. Consulte a tabela de solução de problemas na seção 4.

Toda chamada de ferramenta retorna em até 45 segundos. Leituras grandes podem ser reduzidas com campaign_id.

8. Cotas

Cota	Gratuito	Iniciante	Profissional	Empresarial
Ferramentas de leitura	Sim	Sim	Sim	Sim
Ferramentas de escrita	Não	Sim	Sim	Sim
Criações de campanha por mês	1 (somente web)	10	30	100
Chamadas de escrita por dia (UTC)	Não disponível	3.000	3.000	3.000
Rascunhos de IA por hora	Não disponível	60	60	60

A contagem mensal de criações é compartilhada com campanhas criadas no assistente web do ADM e é redefinida na sua data de faturamento. get_accounts mostra a contagem restante e o horário de redefinição. Quando esgotada, o erro informa seu plano, a contagem mensal e a contagem do próximo plano; fazer upgrade remove o limite imediatamente.
Uma chamada de escrita é qualquer chamada com confirm: true, além de cada upload de imagem. Visualizações não contam.
Limites diários (chamadas de escrita, itens de escrita, itens de visualização e consultas ao Google Ads) são limites de segurança contra automação descontrolada, definidos bem acima do uso normal e iguais em todos os planos pagos. Eles são redefinidos às 00:00 UTC.
Rascunhos de IA (draft_ad_groups e draft_campaign) compartilham um limite horário e não contam como chamadas de escrita. draft_campaign não usa uma criação mensal de campanha por si só; create_search_campaign usa.
O acesso de escrita exige uma chave de leitura e escrita e um plano pago ativo.

9. Por que as ferramentas de escrita não devem ser aprovadas automaticamente

Várias ferramentas de leitura retornam texto escrito por outras pessoas: termos de pesquisa são digitados por qualquer pessoa que vê seus anúncios, e texto de anúncio, texto de ativo e nomes podem vir de colegas ou agências. Um termo de pesquisa pode conter palavras que parecem uma instrução para a ferramenta de IA. O ADM rotula esse conteúdo como dados e pede que a ferramenta de IA ignore instruções dentro dele, mas nenhum modelo de IA é garantido para seguir essa regra todas as vezes.

O prompt de aprovação para ferramentas de escrita é a etapa em que você vê exatamente o que será alterado. Mantenha-o no lugar:

Aprove apenas ferramentas de leitura automaticamente. No Claude Code, permita apenas mcp__adm__get_*; não adicione mcp__adm__* ou ferramentas de escrita individuais à lista de permissões.
Não execute a ferramenta de IA com prompts de aprovação desativados enquanto o servidor ADM estiver conectado.
Leia cada visualização antes de aprovar, especialmente orçamentos, update_ads (editar texto de anúncio envia o anúncio de volta para revisão) e chamadas que definem um status para ATIVADO (set_campaign_status, update_ad_group, set_ad_group_status, set_ad_status, set_keyword_status). update_campaign não pode ativar uma campanha. REMOVED não pode ser desfeito.

10. Rotação de chaves

Crie uma nova chave na página de chaves de API.
Substitua a chave: atualize ADM_API_KEY, ou a chave na configuração MCP da ferramenta de IA e reinicie a ferramenta de IA. O Claude Code armazena o cabeçalho quando o servidor é adicionado, então execute claude mcp remove adm e adicione o servidor novamente (seção 4).
Repita o passo 2 em cada computador que usa a chave antiga.
Observe o horário de "Último uso" da chave antiga. Quando não mudar mais, revogue a chave antiga.

Trate uma chave como uma senha. Não a envie para um repositório nem a escreva em arquivos de projeto. Uma chave colada em um chat permanece no histórico da conversa; rotacione-a se esse histórico puder ser visto por outros. Se uma chave pode ter vazado, revogue-a imediatamente.

11. Alterações que você faz no Google Ads

As ferramentas criam e adicionam. Elas também podem pausar uma campanha, alterar seu nome, orçamento diário, lances e (exceto em Pesquisa) idiomas, adicionar ou remover seus locais, definir ajustes de lance por dispositivo (incluindo exclusão de celular), criar, anexar e redirecionar uma estratégia de lances de portfólio compartilhada, renomear, pausar, ativar, relancear ou remover um grupo de anúncios, ativar, pausar ou remover anúncios e palavras-chave positivas, editar títulos, descrições, URL final e caminhos de um anúncio de pesquisa responsivo existente, adicionar ou remover palavras-chave negativas, pausar ou desvincular ativos e definir opções de URL (parâmetros personalizados, modelo de rastreamento, sufixo de URL final) em uma campanha, grupo de anúncios ou anúncio. Ativar uma campanha é apenas set_campaign_status. REMOVED não pode ser desfeito. Faça estas alterações diretamente no Google Ads:

Excluir um ativo não utilizado da biblioteca de ativos (desvinculá-lo é set_asset_link_status)
Definir segmentação por idioma em uma campanha de Pesquisa (o Google removeu isso em setembro de 2026; a campanha segmenta todos os idiomas)
Desativar recomendações de aplicação automática (Recomendações, depois Aplicação automática)
Configurar o rastreamento de conversões
Adicionar formulário de lead, mensagem comercial, aplicativo móvel e ativos de local
Definir o cronograma de anúncios e segmentos de público
Criar tipos de campanha diferentes de Pesquisa, como Performance Max
Gerenciar cobrança e concluir a verificação do anunciante

12. Histórico de alterações

2026-10-08

O ADM hospedado agora oferece as ferramentas de leitura e rascunhos de IA (draft_campaign, draft_ad_groups). As ferramentas de escrita ainda não estão disponíveis lá; quando estiverem ausentes, um rascunho é apresentado como um plano em vez de ser criado.
get_accounts aceita skill_version e retorna skill_latest_version, skill_update_hint, upgrade_hint e upgrade_url (somente novos campos, sem alteração de quebra; versão do contrato permanece 2026-10-03). Versão do arquivo de habilidade 2026-10-08: veja Atualizar a habilidade.

2026-10-05

Adicionado (somente novas ferramentas, sem alteração de quebra): add_promotions, add_calls, add_business_name, add_business_logo. get_assets types também aceita promotion, call, business_name e business_logo, e set_asset_link_status pausa, ativa ou desvincula-os.

2026-10-04

Adicionado: get_ad_groups, get_paused_summary, find_negative_conflicts, get_conversion_actions, get_customizers, confirm_preview, set_location_bid_adjustments, set_customizer_values. get_campaigns agora inclui CPA desejado, ROAS desejado e a estratégia de portfólio. get_assets filtra por level, types, asset_ids e link_status e pagina com limit / cursor. get_keywords filtra por status, match_type e text_contains. get_ads adiciona text_contains, compact e um performance_label em cada título e descrição. get_location_performance inclui bid_adjustment_percent para um local segmentado.
Mudança de comportamento: get_campaign_setup não retorna mais ativos, a menos que include contenha assets. A inclusão padrão é ad_groups, keywords e ads. Anúncios incluem ad_strength.
set_campaign_status aceita até 50 campanhas e a visualização totaliza o orçamento diário de campanhas que ainda não estão ativadas. Ativar uma campanha de CPC manual avisa quando um CPC máximo de grupo de anúncios ainda é um espaço reservado (0,05 ou menos). update_ads aceita headline_replacements e description_replacements. add_prices rejeita idiomas e moedas não suportados na visualização. add_structured_snippets verifica o cabeçalho contra a tradução oficial para o idioma que você passa. Visualizações de escrita de palavras-chave incluem campaign_name e ad_group_name. Após a aprovação, confirm_preview executa uma visualização apenas do seu preview_id.
Adicionado (somente novas ferramentas, sem alteração de quebra): get_device_performance, set_device_bid_adjustments, get_location_performance. get_campaign_setup agora inclui device_bid_adjustments na campanha e em cada grupo de anúncios. Excluir um local ainda usa update_campaign_locations.
Adicionado (somente novas ferramentas, sem alteração de quebra): update_campaign_locations, set_asset_link_status, get_bidding_strategies, create_bidding_strategy, attach_bidding_strategy, update_bidding_strategy.
update_campaign não rejeita mais uma estratégia de portfólio. Passar bidding desanexa a campanha do portfólio e a visualização nomeia o portfólio que ela deixa.

2026-10-03

Versão do contrato 2026-10-03. Alteração de quebra: update_campaign status aceita apenas PAUSED. Ativar uma campanha é apenas set_campaign_status, após uma solicitação explícita. REMOVED não pode ser desfeito.
Adicionado: set_ad_status, set_keyword_status, set_ad_group_status, add_campaign_negative_keywords, remove_negative_keywords, add_shared_negative_keywords, remove_shared_negative_keywords. Resultados em lote são por item; uma falha não desfaz itens que foram bem-sucedidos.
Adicionado update_ads (somente nova ferramenta, sem alteração de quebra; versão do contrato permanece 2026-10-03): edite um anúncio de pesquisa responsivo no lugar. O ID do anúncio e seu histórico de desempenho permanecem. Não remova o anúncio e adicione um substituto.
Estendido update_campaign com daily_budget (rejeitado em um orçamento compartilhado), bidding (rejeitado em uma estratégia de portfólio) e languages (lista vazia significa todos os idiomas; campanhas de Pesquisa são rejeitadas e nada mais nessa chamada é alterado). Estendido update_ad_group com max_cpc. Palavras-chave get_campaign_setup agora incluem id (o ID do critério).
Adicionado na versão do contrato 2026-09-30 (somente novas ferramentas, sem alteração de quebra): draft_campaign e get_campaign_draft. O ADM cria um rascunho de uma nova campanha de Pesquisa a partir de uma página de destino, incluindo exploração de palavras-chave, agrupamento e anúncios de pesquisa responsivos. Passe o campaign finalizado para create_search_campaign. O limite horário de rascunhos é compartilhado com draft_ad_groups.
Adicionado na versão do contrato 2026-09-30 (somente novas ferramentas, sem alteração de quebra): ferramentas de escrita update_campaign e update_ad_group. Renomeie uma campanha ou grupo de anúncios e/ou pause ou ative em uma única alteração atômica, por exemplo, para marcar por que foi pausado. set_campaign_status continua funcionando inalterado.
Adicionado na versão do contrato 2026-09-30 (somente nova ferramenta e campos, sem alteração de quebra): ferramenta de escrita set_url_options. Defina parâmetros personalizados (mesclados por chave), um modelo de rastreamento e um sufixo de URL final em campanhas, grupos de anúncios ou anúncios, para que um modelo de rastreamento no nível da conta possa registrar de qual um clique veio. get_campaign_setup e get_ads retornam url_options quando qualquer um dos três está definido.

2026-09-30

Primeira versão do servidor MCP da ADM, versão de contrato 2026-09-30.
9 ferramentas de leitura: get_accounts, get_campaigns, get_campaign_setup, get_ads, get_keywords, get_search_terms, get_negative_keywords, get_assets, get_operation.
11 ferramentas de escrita: create_search_campaign, add_ad_groups, add_keywords, add_account_negative_keywords, create_shared_negative_list, attach_shared_negative_list, add_sitelinks, add_callouts, add_structured_snippets, add_prices, set_campaign_status.
Habilidade ADM adm-google-ads para criar campanhas a partir de um plano (seção 3).
Adicionado na mesma versão de contrato (apenas novas ferramentas e campos, sem mudanças que quebrem compatibilidade): ferramentas de escrita add_ads e add_images, ferramentas de rascunho com IA draft_ad_groups e get_ad_group_draft, o endpoint de upload de imagens POST /mcp/uploads, e ativos de imagem em get_assets e get_campaign_setup. A habilidade adiciona os fluxos de rascunho com IA e de imagens.
Documentação movida para /docs/google-ads-skill. A habilidade adiciona relatórios e perguntas, uma conta padrão salva por projeto, e configuração para Codex, Cursor e Windsurf; as instruções do servidor adicionam a mesma regra de conta padrão. No primeiro uso em um projeto, a habilidade sugere prompts que o usuário pode copiar.