Google Ads MCP

Servidor Google Ads MCP

Um servidor MCP local para ler e escrever na API do Google Ads. Gerenciamento completo de campanhas com um fluxo de segurança de pré-visualização/confirmação em toda escrita.

Pré-requisitos

1. Conta do Google Ads Manager (MCC) com um token de desenvolvedor. Verifique o nível de acesso: UI do Google Ads -> Ferramentas e Configurações -> Configuração -> Central de API.
   • Teste: só pode acessar contas de teste. Solicite acesso Básico para operar contas reais (a aprovação pode levar alguns dias).
   • Básico/Padrão: pronto para contas reais.
2. Um projeto do Google Cloud com a API do Google Ads ativada e um cliente OAuth2 do tipo Aplicativo de desktop (fornece um ID de cliente e um segredo de cliente).

Configuração

python -m venv .venv
. .venv/Scripts/activate      # Windows PowerShell: .venv\Scripts\Activate.ps1
pip install -e ".[dev]"

# Mint a refresh token (one-off browser consent):
python scripts/generate_refresh_token.py --client-id XXX --client-secret YYY

cp .env.example .env          # then fill in every value

Se a tela de consentimento OAuth ainda estiver no modo teste, adicione primeiro a conta do Google com a qual você faz login como usuário de teste (Console do Cloud -> APIs e Serviços -> Tela de consentimento OAuth -> Público), caso contrário o consentimento falha com um erro de verificação.

Quando .env contém o ID e o segredo do cliente, python scripts/remint_refresh_token.py reemite um token de atualização expirado ou revogado e reescreve .env no lugar, sem exibir o segredo.

Nunca faça commit de .env; ele está no gitignore e é o único lugar onde credenciais reais devem ficar.

.env chaves: GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET, GOOGLE_ADS_REFRESH_TOKEN, GOOGLE_ADS_LOGIN_CUSTOMER_ID (seu ID MCC, hífens opcionais, exibido no canto superior direito da UI do Google Ads quando conectado à conta de gerente).

Executar os testes

pip install -e ".[dev]"
pytest -v

Registrar com o Claude Code

Use o caminho absoluto do python da venv para que o registro funcione independentemente do diretório a partir do qual o Claude Code é iniciado (o servidor também resolve .env a partir da raiz do projeto, não do diretório atual):

# Windows
claude mcp add google-ads -- "<REPO_PATH>\.venv\Scripts\python.exe" -m google_ads_mcp.server

# macOS / Linux
claude mcp add google-ads -- "<REPO_PATH>/.venv/bin/python" -m google_ads_mcp.server

Adicione --scope user para disponibilizar as ferramentas em todos os projetos, e não apenas neste.

Segurança de escrita

Toda ferramenta de escrita usa pré-visualização por padrão: ela valida a alteração com o validate_only da API e retorna um confirmation_token. Para aplicar, chame a mesma ferramenta novamente com commit=true e esse token. A operação confirmada é exatamente o que foi pré-visualizado. Nada gasta dinheiro até você confirmar.

Ferramentas

Leitura: list_accounts, run_gaql, get_campaigns, get_ad_groups, get_keywords, get_performance.

Escrita (pré-visualização -> confirmação): create_campaign_budget, create_campaign, update_budget, update_campaign_status, create_ad_group, update_ad_group_status, create_responsive_search_ad, add_keywords, add_negative_keywords, apply_mutate.