Google Ads管理MCP服务器

Google Ads MCP

Servidor MCP (Model Context Protocol) que transforma qualquer agente de IA em um gestor completo de trafego e performance para Google Ads.

Suporta o fluxo completo: analise de performance, criacao de campanhas (Search, Display, Shopping, PMax, Demand Gen; Video só leitura/relatório — a API não cria nem edita campanhas de Vídeo), gestao de budget, controle de status, audiencias, extensoes de anuncio, catalogo de produtos e conversoes.

Funciona em modo local (stdio) e remoto (HTTP/SSE), com suporte a deploy no Railway.

Requisitos

• Node.js 20+
• Conta Google Ads com acesso MCC (Manager)
• Token OAuth 2.0 com escopo https://www.googleapis.com/auth/adwords (as tools da Data Manager API — upload_offline_conversions_data_manager, get_data_manager_request_status — pedem também https://www.googleapis.com/auth/datamanager no consentimento; service account já pede os dois)
• Projeto Google Cloud com a Google Ads API ativada e nivel de acesso Explorer, Basic ou Standard. Desde 09/09/2026 o developer token foi descontinuado: o acesso e do projeto Cloud dono do OAuth client (ou da service account) — peca o nivel na pagina "Google Ads API Overview" do projeto. check_api_access diagnostica a configuracao.

Variaveis de ambiente

Instalacao e uso

Modo local (stdio) — Cursor / Claude Code

git clone https://github.com/RaphizSanders/google-ads-mcp.git
cd google-ads-mcp
npm install
npm run build

Configure em ~/.claude.json (ou ~/.cursor/mcp.json):

{
  "mcpServers": {
    "google-ads": {
      "command": "node",
      "args": ["/caminho/absoluto/google-ads-mcp/dist/index.js"],
      "env": {
        "GOOGLE_ADS_CREDENTIALS_PATH": "/caminho/google_ads_token.json",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "1234567890"
      }
    }
  }
}

Multiplas MCCs: Use o mesmo codigo com entradas diferentes no JSON, mudando apenas GOOGLE_ADS_LOGIN_CUSTOMER_ID.

Modo HTTP (remoto)

PORT=3333 GOOGLE_ADS_CREDENTIALS_PATH=./creds.json \
  GOOGLE_ADS_LOGIN_CUSTOMER_ID=123 \
  ALLOWED_CUSTOMER_IDS=1234567890 MCP_ALLOWED_HOSTS=localhost,127.0.0.1 \
  MCP_API_KEY=sua_chave node dist/index.js

Expor por HTTP exige MCP_API_KEY, MCP_ALLOWED_HOSTS e ALLOWED_CUSTOMER_IDS — o processo recusa iniciar sem os tres, em modo de leitura ou de escrita. O modo stdio (uso local no Cursor/Claude Code) nao passa por nenhuma dessas checagens.

Deploy no Railway

1. Crie projeto no Railway e conecte o repositorio
2. Configure variaveis de ambiente
3. URL do endpoint: https://<seu-app>.up.railway.app/mcp

Modo somente leitura

Para integrações analíticas, defina GOOGLE_ADS_READ_ONLY=true. Nesse modo:

• tools/list publica somente as 139 tools classificadas como leitura;
• as 206 tools de criação, edição, upload e exclusão não são registradas;
• chamadas diretas à camada de mutação também são recusadas antes de qualquer acesso à API;
• uma tool nova e ainda não classificada permanece bloqueada por padrão.

O modo é opt-in para não alterar deployments existentes. Em ambientes de cliente, ele exige ALLOWED_CUSTOMER_IDS e credenciais do MCP. Valores inválidos para GOOGLE_ADS_READ_ONLY fazem o processo falhar na inicialização, evitando configuração ambígua.

Quando o modo read-only roda por HTTP (PORT definido), MCP_API_KEY e MCP_ALLOWED_HOSTS são obrigatórios. O processo recusa iniciar se qualquer um estiver ausente. Para hospedagem, prefira GOOGLE_ADS_CREDENTIALS_JSON como secret write-only; o refresh token permanece somente em memória e nunca é gravado no filesystem do container.

list_accounts filtra a descoberta pela allowlist quando o servidor está exposto por HTTP (PORT definido). Aí a ausência ou lista vazia nunca significa wildcard: o processo recusa iniciar e a guarda de cada tool também nega o acesso, como defesa em profundidade.

Em stdio o critério é outro, e de propósito: o processo é iniciado pelo próprio cliente com a credencial dele, não há superfície de rede nem outro inquilino para vazar, e list_accounts é o ponto de descoberta — o id que você precisaria colocar na allowlist é justamente o que se vem buscar aqui. Por isso uma allowlist vazia mantém o significado original de "sem filtro". Passar ALLOWED_CUSTOMER_IDS em stdio continua funcionando e restringe normalmente.

Tools (345 total — atualizado 2026-09-23)

As 95 do núcleo estão nesta seção; as 250 das áreas (segmentação, lances, negativas, conversões, PMax, Shopping, Demand Gen, públicos, diagnóstico, administração do MCC...) estão em Tools por área, com documentação em docs/tools/.

Descoberta de contas

Insights e analise

Criativos e assets

GAQL (Query Language)

Criacao de campanhas

Ad Groups e Anuncios

Keywords

PMax — Asset Groups

Targeting

Bid Adjustments

Gestao de campanha

Extensoes de anuncio

Conversoes

Planejamento e recomendacoes

Labels

Remarketing

Merchant Center

Tools por área (250 — módulos em src/tools/)

Além das 95 do núcleo (acima), cada área tem um módulo próprio e uma página com parâmetros, fluxos e limitações em docs/tools/. O grupo de cada área é o nome usado em GOOGLE_ADS_TOOL_GROUPS. L = leitura, E = escrita (aceita validateOnly).

Segmentação geográfica e de idioma

Grupo targeting-geo · 5 tools · documentação

Ajustes de lance, programação e demografia

Grupo bid-modifiers · 9 tools · documentação

Posicionamentos, exclusões e brand safety

Grupo placements-brand-safety · 16 tools · documentação

Anúncios responsivos de Pesquisa, customizadores e auditoria de anúncios

Grupo rsa-ads · 8 tools · documentação

Extensões (assets vinculados), WhatsApp e formulário de lead

Grupo extensions · 11 tools · documentação

Biblioteca de assets e locais do Perfil da Empresa

Grupo asset-library · 9 tools · documentação

Palavras-chave, termos de pesquisa e DSA

Grupo keywords · 5 tools · documentação

Palavras-chave negativas em todos os níveis

Grupo negatives · 7 tools · documentação

Planejador de palavras-chave e recomendações

Grupo planner-recommendations · 6 tools · documentação

Orçamentos, ritmo de gasto e grupos de campanhas

Grupo budgets · 10 tools · documentação

Estratégias de lance, simulações, sazonalidade e datas de campanha

Grupo bidding · 12 tools · documentação

Experimentos, rastreamento de URL, rótulos e aquisição de clientes

Grupo experiments-tracking · 21 tools · documentação

Ações e metas de conversão

Grupo conversions-core · 8 tools · documentação

Importação offline, ajustes de conversão, chamadas e GCLID

Grupo conversions-offline · 7 tools · documentação

Regras de valor, detalhamento de conversões, lift e leads

Grupo conversions-reporting · 11 tools · documentação

Performance Max: criação e gestão de asset groups

Grupo pmax-assets · 5 tools · documentação

Performance Max: sinais, automação, marca, prévias e combinações

Grupo pmax-signals · 15 tools · documentação

Shopping, Merchant Center e grupos de produtos

Grupo shopping · 8 tools · documentação

Relatórios de varejo, status de produtos, canais do PMax e listas de marcas

Grupo retail-reporting · 10 tools · documentação

Demand Gen e remarketing dinâmico de varejo em Display

Grupo demand-gen · 7 tools · documentação

Vídeo, YouTube e anúncios de Display

Grupo video-display · 8 tools · documentação

Públicos, remarketing e Customer Match

Grupo audiences · 11 tools · documentação

Diagnóstico de veiculação, parcela de impressões e reprovações

Grupo diagnostics · 6 tools · documentação

Relatórios de posicionamento, landing page, redes e visão do MCC

Grupo reports · 4 tools · documentação

Autenticação, configurações da conta e metadados de campos

Grupo account-auth · 7 tools · documentação

Administração do MCC: contas, vínculos, usuários, faturamento e edição em massa

Em HTTP com allowlist explícita, list_invoices só retorna uma fatura se todos os seus orçamentos identificarem contas autorizadas. Uma fatura consolidada que inclua outra conta, ou sem atribuição verificável, é recusada inteira: ocultar nomes mas mostrar o total ainda revelaria dados financeiros externos ao escopo. Não é calculada uma fatura parcial. O modo local/agência permanece compatível.

Grupo account-admin · 24 tools · documentação

Resources (5 total)

Prompts (9 total)

Compatibilidade com a Google Ads API (varredura 2026-09-09)

Enums e campos foram validados contra os protos oficiais da v25.

PMax Creation — Notas Importantes (API v23+)

A criacao de campanhas Performance Max na API v23 tem particularidades criticas:

Fluxos de criacao de campanha

Search

create_campaign (SEARCH) → create_ad_group → create_ad (RSA) → create_keyword
→ set_campaign_locations → set_geo_target_type (PRESENCE para negocio local)
→ create_sitelink_extension → create_callout_extension

AI Max em campanha de Pesquisa

set_ai_max_settings (enableAiMax + controles)
→ update_ad_group (disableSearchTermMatching nos grupos que nao devem expandir, ex.: marca)
→ get_ai_max_report (termos, combinacoes, landing pages)

• O que cada controle faz: enableAiMax liga o AI Max; textCustomization e finalUrlExpansion sao as automacoes TEXT_ASSET_AUTOMATION e FINAL_URL_EXPANSION_TEXT_ASSET_AUTOMATION; termExclusions (ate 25, 30 caracteres) e messagingRestrictions (ate 40, 300 caracteres) orientam os textos gerados. As duas listas substituem a atual ([] limpa).
• Escrita minima: o updateMask leva so os campos que mudam; valor igual ao atual nao e reenviado; os tipos de automacao nao pedidos sao preservados. Nao mexe em orcamento, lances, segmentacao nem palavras-chave.
• Com AI Max ligado a API trata as palavras-chave como correspondencia ampla e trava keyword_match_type. Em Shopping, a personalizacao de texto vem sempre ligada com o AI Max.
• Leitura dos relatorios: search_term_view com match_source e ai_max_search_term_ad_combination_view se sobrepoem — nunca some metricas entre elas. Termos de baixo volume ficam fora por privacidade, entao os totais ficam abaixo do total da campanha.

Imagens em campanha de Pesquisa

upload_image_asset (sobe cada imagem; guarde o resource name)
→ link_campaign_image_assets (campaignId + assetResourceNames)
→ list_campaign_image_assets (confirma vinculo e analise)

• O que o vinculo faz: cria um campaignAsset com fieldType: AD_IMAGE e status: ENABLED. Nao mexe em campanha, orcamento, lances nem segmentacao.
• Validacoes antes de gravar: a campanha existe na conta e e SEARCH; cada imagem existe na conta e e do tipo IMAGE; resource name de outra conta e recusado sem chamar a API.
• Idempotente: imagem ja vinculada nao e recriada; vinculo PAUSED continua pausado (a tool nunca reativa). O retorno separa criados, ja existentes e erros por imagem.
• Testar em producao sem gravar: rode com GOOGLE_ADS_DRY_RUN=true — a API valida o vinculo (validateOnly) e nada e gravado.
• Regras do Google: ao menos uma imagem quadrada 1:1 (min. 300x300); paisagem 1.91:1 opcional (min. 600x314); ate 20 imagens por campanha; a conta precisa ser elegivel a imagens em Pesquisa. Vinculo novo fica PENDING / ASSET_UNDER_REVIEW e so veicula depois de aprovado — list_campaign_image_assets mostra isso e avisa quando falta imagem quadrada.

Performance Max (E-commerce)

upload_image_asset (landscape, square, logo)
→ create_pmax_campaign (com merchantId, headlines, descriptions, imagens)
→ set_campaign_locations

Display

create_display_campaign → create_ad_group → upload_image_asset
→ create_responsive_display_ad → update_ad_group_targeting (audiencia)

Video (YouTube)

Video programatico: create_demand_gen_campaign → create_demand_gen_ad_group → create_demand_gen_ad
(upload_youtube_video sobe o arquivo para o YouTube, se preciso).
Campanhas VIDEO existentes: so leitura e relatorio (get_video_performance, get_placement_report) —
a API nao cria nem altera campanhas de Video.

Shopping

create_shopping_campaign (merchantId) → create_ad_group
→ Produtos puxados automaticamente do Merchant Center

Remarketing (Carrinho Abandonado)

create_remarketing_list (URL /cart, excluir /thank-you, 30 dias)
→ create_display_campaign → create_ad_group
→ update_ad_group_targeting (vincular lista)
→ create_responsive_display_ad

Bidding Strategies suportadas

Seguranca

• Tudo PAUSED por padrao: Todas as tools de criacao criam objetos pausados.
• Budgets em MICROS: R$1,00 = 1.000.000 micros. Descricoes explicitas.
• MCP_API_KEY: Protege o endpoint HTTP.
• ALLOWED_CUSTOMER_IDS: Escopo de contas. Obrigatoria sob HTTP (ausente/vazia derruba o boot), opcional em stdio. Use * para servir todo o MCC (agencia) ou a lista de IDs para isolar um cliente por servico.
• GOOGLE_ADS_DRY_RUN: Valida payloads de escrita contra a API sem gravar (validateOnly).
• validateOnly por chamada: toda tool de escrita aceita validateOnly: true — a API valida a operacao inteira (validate_only) e nada e gravado; a resposta comeca com VALIDATE-ONLY. As criacoes de campanha (Search, Display, Shopping, Demand Gen, PMax), asset groups, extensoes e listas de negativas vao num unico googleAds:mutate atomico com IDs temporarios, entao o validateOnly valida o pedido inteiro. Recusam o modo, sem enviar nada: endpoints sem validate_only (apply_recommendation, dismiss_recommendation) e as poucas tools que ainda gravam em passos dependentes (create_video_ad, create_batch_job, create_location_sync_asset_set, upload_customer_match_members).
• Delete com confirmacao: confirm: true obrigatorio para remocao.
• OAuth auto-refresh: Token renova automaticamente, persiste no arquivo.

Auth — Formato do credentials JSON

{
  "token": "ya29.xxxxx",
  "refresh_token": "1//xxxxx",
  "token_uri": "https://oauth2.googleapis.com/token",
  "client_id": "xxxxx.apps.googleusercontent.com",
  "client_secret": "xxxxx",
  "scopes": ["https://www.googleapis.com/auth/adwords"],
  "expiry": "2026-03-18T12:00:00.000Z"
}

Atualizacao

cd google-ads-mcp
git pull
npm ci
npm run build
# Reiniciar Claude Code para carregar

Licenca

MIT