google-ads-mcp

Servidor MCP próprio para criar e gerenciar campanhas no Google Ads via Google Ads API (REST + GAQL) — Pesquisa, Performance Max, Shopping, Display e Vídeo (YouTube), com palavras-chave, anúncios responsivos, extensões (sitelinks, callouts, snippets, chamada), Customer Match, keyword research e relatórios. 52 ferramentas. Irmão do meta-ads-mcp — mesma arquitetura e padrões de segurança.

Pré-requisitos no Google

1. Projeto no Google Cloud Console com a Google Ads API ativada.
2. Credenciais OAuth2 (tipo "Desktop app") → client_id + client_secret.
3. Refresh token — gere uma vez com o fluxo OAuth2 (escopo https://www.googleapis.com/auth/adwords).
4. Developer token — no Google Ads: Ferramentas → Configuração → Central de API.

   Começa em modo teste (só contas de teste). Para operar contas reais, solicite Basic Access no mesmo painel — aprovação leva alguns dias.

5. Para portfólio de clientes: o ID da MCC (conta de administrador) em GOOGLE_ADS_LOGIN_CUSTOMER_ID.

Instalação (Claude Code)

Não precisa clonar nada — roda direto via npx:

claude mcp add google-ads \
  --env GOOGLE_ADS_CLIENT_ID=... \
  --env GOOGLE_ADS_CLIENT_SECRET=... \
  --env GOOGLE_ADS_REFRESH_TOKEN=... \
  --env GOOGLE_ADS_DEVELOPER_TOKEN=... \
  --env GOOGLE_ADS_LOGIN_CUSTOMER_ID=1234567890 \
  -- npx -y @creativeproject/google-ads-mcp

O Claude Code sobe e derruba o servidor sozinho a cada sessão. Reinicie a sessão e as ferramentas do google-ads estarão disponíveis.

Outros clientes MCP (Claude Desktop, Cursor, etc.)

{
  "mcpServers": {
    "google-ads": {
      "command": "npx",
      "args": ["-y", "@creativeproject/google-ads-mcp"],
      "env": {
        "GOOGLE_ADS_CLIENT_ID": "...",
        "GOOGLE_ADS_CLIENT_SECRET": "...",
        "GOOGLE_ADS_REFRESH_TOKEN": "...",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "...",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "1234567890"
      }
    }
  }
}

Configuração (variáveis de ambiente)

| Variável | Obrig. | Descrição | |---|---|---| | GOOGLE_ADS_CLIENT_ID / GOOGLE_ADS_CLIENT_SECRET | ✓ | Credenciais OAuth2 do Google Cloud | | GOOGLE_ADS_REFRESH_TOKEN | ✓ | Refresh token (o access token é renovado automaticamente) | | GOOGLE_ADS_DEVELOPER_TOKEN | ✓ | Developer token da Central de API | | GOOGLE_ADS_LOGIN_CUSTOMER_ID | | ID da MCC (para operar contas de clientes) | | GOOGLE_ADS_CUSTOMER_ID | | Conta padrão (toda ferramenta aceita customer_id por chamada) | | GOOGLE_ADS_API_VERSION | | Default v21 — versões expiram ~1 ano, ajuste quando necessário | | GOOGLE_ADS_MAX_BUDGET_MICROS | | Guard-rail: teto de orçamento em micros | | MCP_HTTP_AUTH_TOKEN / MCP_HTTP_PORT | | Modo HTTP remoto (porta padrão 3536) |

Modo HTTP remoto (opcional)

Para hospedar e usar no claude.ai ou compartilhar com a equipe. Exige MCP_HTTP_AUTH_TOKEN (recusa iniciar sem autenticação). Ver Desenvolvimento abaixo.

Desenvolvimento (clonando o repositório)

Só necessário para contribuir ou modificar o código:

git clone https://github.com/wayter95/google-ads-mcp.git
cd google-ads-mcp
npm install
cp .env.example .env   # preencha as credenciais
npm run dev            # stdio com watch
npm run start:http     # modo HTTP remoto
npm test               # testes (unit + integração do servidor MCP em memória)
npm run inspector      # debug visual

⚠️ Unidade monetária: MICROS

O Google Ads usa micros: 1.000.000 micros = 1 unidade da moeda.

| Valor real | Em micros | |---|---| | R$ 2,00 (CPC) | 2000000 | | R$ 50,00/dia | 50000000 | | R$ 1.000,00 | 1000000000 |

Nos relatórios, divida cost_micros por 1.000.000. (No meta-ads-mcp são centavos — não confunda.)

Ferramentas

Conta e leitura

list_accessible_customers · list_client_accounts (portfólio da MCC) · get_account · run_gaql_query (qualquer consulta GAQL — a ferramenta mais poderosa de leitura) · list_conversion_actions

Campanhas e orçamentos

create_campaign_budget (orçamento é recurso separado, criado antes) · create_campaign (Search; estratégias MANUAL_CPC / MAXIMIZE_CLICKS / MAXIMIZE_CONVERSIONS com target CPA / MAXIMIZE_CONVERSION_VALUE com target ROAS; redes; datas) · update_campaign · update_campaign_budget · list_campaigns · remove_campaign

Grupos de anúncios

create_ad_group · update_ad_group · list_ad_groups

Palavras-chave

add_keywords (EXACT/PHRASE/BROAD, lance individual opcional) · add_negative_keywords (nível campanha) · list_keywords · remove_criterion · generate_keyword_ideas (keyword research: volume, concorrência, CPC estimado por semente ou URL)

Anúncios

create_responsive_search_ad (3–15 títulos, 2–4 descrições, pinning opcional) · update_ad_status · list_ads (com status de aprovação)

Segmentação

search_geo_targets (nomes → IDs de localização) · set_location_targeting (incluir/excluir) · set_language_targeting · search_languages · list_campaign_criteria (auditar segmentação atual)

Relatórios

get_campaign_performance · get_keyword_performance (com índice de qualidade) · get_search_terms_report (termos reais — base para negativas) · get_account_performance (agregado ou por dia)

Performance Max

create_pmax_campaign · create_pmax_asset_group (asset group completo em uma operação atômica: títulos, descrições, nome da empresa, imagens, logo, vídeos — via googleAds:mutate com IDs temporários) · add_pmax_search_themes (sinais de temas de pesquisa) · list_pmax_asset_groups (com ad_strength)

Shopping

create_shopping_campaign (Merchant Center, feed label, prioridade 0–2, CPC manual ou tROAS) · create_shopping_ad_group (grupo + anúncio de produto + listing group raiz de uma vez)

Display

create_display_campaign · create_responsive_display_ad (títulos, descrições, imagens paisagem/quadrada, logo)

Vídeo (YouTube)

create_video_campaign (CPV manual / tCPM) · create_video_ad (asset do YouTube + grupo + anúncio in-stream pulável em uma chamada). ⚠️ Alguns subtipos de vídeo são restritos via API; o vídeo precisa estar publicado no YouTube.

Extensões (assets)

create_sitelink_assets · create_callout_assets · create_structured_snippet_asset · create_call_asset — todas criam E vinculam à campanha em uma chamada · create_image_asset_from_url (upload de imagens para Display/PMax) · list_assets

Customer Match

create_customer_match_list · add_users_to_customer_match_list (hash SHA-256 local de emails/telefones/endereços — nada em texto puro sai da máquina; executa o fluxo completo de upload job em uma chamada; processamento em até 24h) · list_customer_match_lists. Requer elegibilidade da conta.

Orquestração

create_full_search_campaign — campanha completa em uma chamada: orçamento → campanha → geo/idioma/negativas → grupo → palavras-chave → RSA. Tudo PAUSED, com rollback automático (remove campanha e orçamento se qualquer etapa falhar).

Comportamentos de segurança e resiliência

• Tudo nasce PAUSED — nada gasta até status: ENABLED explícito.
• validate_only em toda mutação — dry run nativo do Google.
• Guard-rail de orçamento via GOOGLE_ADS_MAX_BUDGET_MICROS.
• Retry com backoff (2s → 6s → 15s) em 429/503/RESOURCE_EXHAUSTED.
• OAuth2 automático — access token renovado e cacheado; erros da API traduzidos para mensagens legíveis (incluindo os detalhes de campo do formato protobuf).
• Guia embutido para a IA — instructions no handshake + resource google-ads://guide + ferramenta get_usage_guide.
• HTTP remoto só com autenticação.

Fluxo típico

1. list_client_accounts                     → portfólio da MCC
2. search_geo_targets(["São Paulo"])        → IDs de localização
3. generate_keyword_ideas(["advocacia"])    → volume e CPC estimado
4. create_full_search_campaign(...)         → tudo criado PAUSED, com rollback
5. update_campaign(status: ENABLED)         → ativar
6. get_search_terms_report(...)             → otimização contínua
7. add_negative_keywords(...)               → cortar gasto desperdiçado