O Google Ads MCP permite que um agente de IA consulte campanhas, leia métricas e prepare mudanças na sua conta de anúncios. O servidor oficial do Google não dá carta branca ao agente: ações de escrita passam por uma etapa de proposta e confirmação.
Neste guia, você vai configurar o modo mais seguro para uso individual, testar consultas de leitura e entender quando usar um container com OAuth. Não conecte uma conta de produção antes de validar o fluxo em uma conta de testes.
O que o Google Ads MCP faz e o que ele não faz
MCP é um protocolo que deixa um cliente de IA chamar ferramentas externas. Neste caso, o servidor expõe consultas GAQL, descoberta de contas acessíveis, metadados de campos, criação de ativos e gestão de rótulos.
Ele não cria uma campanha inteira por linguagem natural. As mutações disponíveis hoje se concentram em ativos, uploads de vídeo e rótulos. Ainda assim, isso é suficiente para causar impacto real na conta. Por isso o projeto exige um fluxo de proposta e confirmação para cada ação de escrita.

✅ O que você ganha e ⚠️ o que você não ganha
✅ O que você ganha
- Consultas GAQL para campanhas, grupos, custos, cliques e métricas disponíveis na API.
- Descoberta das contas Google Ads às quais suas credenciais têm acesso.
- Ferramentas de metadados para saber quais campos podem entrar em uma consulta.
- Auditoria estruturada de chamadas de ferramentas.
- Validação antes de mudanças em ativos e rótulos.
⚠️ O que você não ganha
- Autorização para ignorar políticas do Google Ads ou consentimento de usuários.
- Segurança automática se você conectar um agente com permissões amplas.
- Um substituto para conferir orçamento, conversões e mudanças de campanha no painel.
- Uma configuração pronta para equipes sem configurar OAuth, armazenamento e controles de acesso.
Escolha o modo de instalação certo
| Modo | Transporte | Indicado para | Risco principal |
|---|---|---|---|
| ADC local | stdio | Uma pessoa usando Claude Code, Cursor ou VS Code no próprio PC | O caminho do arquivo de credencial fica na configuração do cliente |
| Container local | HTTP em 127.0.0.1 | Separar segredos do cliente MCP | Exige OAuth proxy e armazenamento de estado |
| Cloud Run | HTTP público com OAuth | Equipe e acesso remoto | Precisa de identidade, URL pública, logs e política operacional |
Antes de instalar: crie o mínimo de permissões
Você precisa de Python 3.11 ou mais novo, pipx, Google Cloud CLI e um projeto no Google Cloud com a Google Ads API ativada. Também precisa de uma identidade que já tenha acesso à conta Google Ads.
Se você atende contas por uma conta de administrador, o MCC, anote o ID dela. O servidor aceita o valor GOOGLE_ADS_LOGIN_CUSTOMER_ID como padrão. Isso não concede acesso novo; apenas informa qual conta gerenciadora deve ser usada nas chamadas.
Passo 1: instale as ferramentas locais
python3 --version
pipx --version
gcloud --version
Se algum comando falhar, instale a ferramenta antes de continuar. Em macOS e Linux, o gerenciador de pacotes da distribuição pode instalar Python e pipx. No Windows, use Python oficial, pipx e Google Cloud CLI.
Passo 2: ative a Google Ads API no projeto
Abra o projeto no Google Cloud Console e ative a Google Ads API. Depois, crie um cliente OAuth do tipo Desktop para o uso local. Baixe o JSON em um diretório protegido. Ele contém o ID do cliente e não deve entrar em Git, Drive compartilhado ou chat.
Passo 3: gere Application Default Credentials
O modo local usa ADC, as credenciais que o Google Cloud CLI grava para aplicativos locais. Execute o comando abaixo e troque o caminho pelo JSON do cliente OAuth.
gcloud auth application-default login
--scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform
--client-id-file=/caminho/seguro/client-secret.json
O navegador vai pedir login e consentimento. Ao terminar, o gcloud mostra o caminho do arquivo de credencial gerado. Guarde esse caminho. Ele será usado pelo cliente MCP, não publicado em um repositório.
Passo 4: comece com configuração somente leitura
O pacote vem com categorias customers, search, metadata, labels e assets. Crie um arquivo tools_config.yaml e desabilite as duas últimas. Assim o agente pode consultar dados, mas não criar ativos ou rótulos.
namespaces:
customers: true
search: true
metadata: true
labels: false
assets: false
Salve em um diretório privado, por exemplo ~/.config/google-ads-mcp/tools_config.yaml. Depois defina a variável GOOGLE_ADS_MCP_TOOLS_CONFIG apontando para esse arquivo.
Passo 5: configure o cliente MCP
Para Claude Code, Cursor ou VS Code, adicione um bloco no arquivo de configuração do cliente. O exemplo abaixo usa pipx e fixa o projeto pelo repositório. Em ambiente de produção, prefira uma versão publicada do pacote em vez de seguir a branch principal.
{
"mcpServers": {
"google-ads-mcp": {
"command": "pipx",
"args": [
"run",
"--spec",
"git+https://github.com/googleads/google-ads-mcp.git",
"google-ads-mcp"
],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/caminho/mostrado-pelo-gcloud/credentials.json",
"GOOGLE_CLOUD_PROJECT": "SEU_PROJECT_ID",
"GOOGLE_ADS_MCP_TOOLS_CONFIG": "/caminho/seguro/tools_config.yaml"
}
}
}
}
Se você usa MCC, acrescente GOOGLE_ADS_LOGIN_CUSTOMER_ID com o ID numérico da conta administradora. Não inclua hífens se sua configuração ou cliente tratar o valor como número.
Passo 6: teste primeiro a descoberta de contas
Reinicie o cliente de IA e confirme que o servidor aparece conectado. Em seguida, faça um pedido simples: “Liste as contas Google Ads às quais tenho acesso”. A ferramenta esperada é customers_list_accessible_customers.
Não comece pedindo relatórios de toda a conta. Primeiro identifique um customer_id. Depois use um pedido limitado, como campanhas ativas e custo dos últimos sete dias. Isso reduz erro de escopo e facilita conferir se o agente escolheu a conta certa.
Passo 7: use GAQL com perguntas verificáveis
GAQL é a linguagem de consulta da Google Ads API. Peça ao agente que mostre a consulta antes de executá-la. Uma pergunta segura é: “Para o cliente 1234567890, mostre campanhas ativas, impressões, cliques e custo nos últimos sete dias; traga a GAQL usada”.
Se ele não souber um campo, use metadata_get_resource_metadata para consultar o schema. Isso é melhor do que deixar o modelo inventar nomes de campos.
Como liberar mudanças sem entregar a conta ao agente
Quando quiser criar um ativo ou rótulo, habilite a categoria correspondente no YAML. O servidor aplica duas etapas. Primeiro, a ferramenta roda em validate_only=true, devolve uma lista compreensível de mudanças e um checksum criptográfico. Depois de revisar, você repete exatamente os parâmetros com validate_only=false e o checksum.
O checksum impede que uma proposta aprovada seja alterada antes da execução. Mesmo assim, a revisão humana é obrigatória. Confira cliente, conta, nome, texto, URL, escopo e impacto antes de confirmar.
Container: quando você não quer segredo no cliente
Em máquinas compartilhadas ou equipes, o README recomenda executar o servidor em container com OAuth proxy. O cliente MCP aponta para http://localhost:8080/mcp, enquanto segredos e estado ficam no container e no volume associado.
docker build --tag google-ads-mcp:latest .
docker run -d --name google-ads-mcp
-p 127.0.0.1:8080:8080
--env-file /caminho/absoluto/google-ads-mcp.env
-v google-ads-mcp-oauth:/var/lib/google-ads-mcp:rw
--read-only --security-opt no-new-privileges --cap-drop ALL
google-ads-mcp:latest
O binding em 127.0.0.1 é intencional. Não exponha a porta 8080 para a internet sem proxy, autenticação, HTTPS e política de acesso. Para equipe remota, Cloud Run pode fazer sentido, mas aumenta a responsabilidade de logs, chaves, armazenamento de tokens e URL pública.
A prova: a suíte do projeto passou
A redação clonou o commit 44ca777, instalou o pacote e dependências de teste em ambiente isolado e executou a suíte indicada pelo projeto. Foram 116 testes concluídos com sucesso e 2 ignorados. Isso valida regras internas, configuração, auditoria e fluxo de proposta e confirmação. Não testa uma conta Google Ads real nem autoriza mudanças em campanhas.
Erros comuns
- ❌ Servidor conectado, mas sem contas
Causa: a identidade OAuth não tem acesso a nenhuma conta Ads. Solução: confira o usuário no painel e teste a descoberta de clientes. - ❌ “Insufficient authentication scopes”
Causa: ADC foi criado sem o escopo de Ads. Solução: repita o login comhttps://www.googleapis.com/auth/adwords. - ❌ O agente tenta criar algo mesmo em modo leitura
Causa: categoriasassetsoulabelsficaram ativas. Solução: desligue-as no YAML e reinicie o servidor. - ❌ Conta de cliente não responde via MCC
Causa: faltalogin_customer_id. Solução: passe o ID do administrador por chamada ou variável de ambiente. - ❌ O servidor HTTP abre para a rede inteira
Causa: porta publicada sem endereço de loopback. Solução: use-p 127.0.0.1:8080:8080ou implemente proteção de borda.
Perguntas frequentes
O agente pode pausar campanhas?
O README atual destaca ativos, uploads de vídeo e rótulos como ações de escrita. Não assuma que ele controla campanhas inteiras sem conferir as ferramentas habilitadas na sua versão.
Posso usar conta de produção?
Pode, mas comece só com leitura e com uma conta cuja estrutura você conheça. Use conta de teste para validar propostas de escrita.
O Google recebe dados do agente?
O projeto informa que chamadas à API incluem um cabeçalho de telemetria MCP. Além disso, o cliente de IA ao qual você conecta o servidor recebe os dados necessários para responder ao pedido.
Posso usar Claude Code?
Sim. O README informa que o formato mcpServers funciona em Claude Code, Cursor e VS Code. Ajuste o arquivo de configuração do cliente.
Qual opção é mais segura?
Para uma pessoa, ADC local com ferramentas de leitura apenas. Para equipe, container ou Cloud Run com OAuth, armazenamento protegido e logs auditáveis.
O Google Ads MCP é útil quando o objetivo é encurtar a distância entre pergunta e dado, não transferir o controle da conta para um chatbot. Trate o agente como um analista júnior rápido: ele pesquisa, resume e propõe; você decide o que entra no ar.
Descubra mais sobre noticiAI
Assine para receber nossas notícias mais recentes por e-mail.

1 comentário