Integrates with the Google Ads API (v23) to manage Google Ads accounts via 92 tools, including account diagnostics and policy audits, budget pacing and bid strategies, Search and Performance Max campaign creation, keyword research, RSA and asset management, auction competitor insights, and offline/enhanced conversion uploads.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Google Ads Expert MCP Server audit my account health and flag any policy violations"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Servidor Model Context Protocol (MCP) de nível empresarial para gestão autônoma de contas do Google Ads via Inteligência Artificial (Antigravity, Cursor, Claude Code, Claude Desktop e agentes autônomos).
Integra diretamente com a Google Ads API (v23) disponibilizando 92 ferramentas atômicas e de inteligência operacional, cobrindo desde auditorias 360° com diagnóstico preventivo de suspensão até criação completa de campanhas PMax/Search, controle de orçamentos, inteligência competitiva e conversões otimizadas para leads (Enhanced Conversions).
🛡️ Blindagem & Diagnóstico 360° de Conta: Detecção proativa de Verificação de Identidade do Anunciante (deadlines, risco de pausa e URL de ação), alertas críticos de faturamento, suspensão e motivos de bloqueio de veiculação (campaign.primary_status_reasons).
📊 Pacing Financeiro & Run Rate: Ferramenta dedicada para monitorar a velocidade de consumo da verba no mês corrente (THIS_MONTH), projeção de fechamento (burn rate) e cálculo do orçamento diário ideal para evitar estouros ou sub-investimento.
🎯 Performance Max (PMax) 360°: Criação completa de PMax, injeção de Search Themes, vinculação de sinais de audiência (Audience Signals) e binding automatizado de assets de texto (Headlines, Long Headlines, Descriptions).
🔍 Radar Competitivo no Leilão: Comparação temporal automática (últimos 7 dias vs. últimos 30 dias) para identificar novos concorrentes no leilão (NEW_ENTRANT) e concorrentes com alta agressiva de lances (SURGING_AGGRESSIVE).
⚖️ Raio-X de Políticas & Recursos: Auditoria cirúrgica de anúncios reprovados (DISAPPROVED), limitados (APPROVED_LIMITED) e em análise de recurso (UNDER_APPEAL), mapeando tópicos de política violados.
⚡ Closed-Loop & Enhanced Conversions: Atribuição offline e Enhanced Conversions for Leads com normalização e hashing SHA-256 nativo de e-mails/telefones (individual ou em lote).
🌐 Hardened Cloud Deployment: Pronto para operar 24/7 na nuvem via Coolify / Docker com transporte duplo: Streamable HTTP (POST /mcp com SSE chunked) e SSE legado (GET /sse), rate limiting in-memory e proteção anti-indexing.
Related MCP server: Complete Google Ads API v21 MCP Server
Agentes de IA (Antigravity / Claude / Cursor)
│
│ Protocolo MCP (Streamable HTTP / SSE)
▼
┌──────────────────────────────────────────────────────────┐
│ Hardened Worker Engine (start_worker.py) │
│ • Rate Limiting (120 req/60s) • Token Bearer Auth │
│ • FastMCP Service Hub • Healthcheck (/health) │
└───────────────────────────┬──────────────────────────────┘
│ 92 Tools Expostas
▼
┌──────────────────────────────────────────────────────────┐
│ MCP Server Layer (logic.py) │
│ • ResourceResolver (ID numérico ou Nome amigável) │
│ • GAQL Linter & Dense Protobuf Serializer │
│ • Lógica de Negócio, Pacing & Diagnósticos │
└───────────────────────────┬──────────────────────────────┘
│ Google Ads API Client (v23)
▼
Google Ads API / Sua Conta MCCFerramenta | Tipo | Descrição |
| REPORT | Status da Verificação de Identidade do Anunciante, deadlines e URL oficial para envio de documentos. |
| REPORT | Diagnóstico 360° consolidando status da conta, billing, verificação e bloqueios operacionais. |
| REPORT | Detalha anúncios reprovados, limitados e em recurso ( |
| REPORT | Visão consolidada da conta: custo, cliques, conversões, ROAS e status das campanhas. |
| REPORT | Audita recursos e recursos habilitados para a conta no Google Ads. |
| REPORT | Auditoria de histórico de alterações nos últimos N dias (quem alterou e o quê). |
| REPORT | Lista recomendações oficiais do Google Ads com métricas de impacto estimadas. |
Ferramenta | Tipo | Descrição |
| REPORT | Análise de queima de verba mensal, projeção final e orçamento diário ideal sugerido. |
| MUTATION | Atualiza o orçamento diário de uma campanha (em Reais). |
| MUTATION | Ajusta ou remove o teto de lance máximo de CPC em campanhas Maximizar Cliques ( |
| MUTATION | Cria um orçamento compartilhado entre múltiplas campanhas. |
| MUTATION | Aplica um orçamento compartilhado a uma campanha existente. |
| MUTATION | Cria estratégia de lances de portfólio (Target CPA, Target ROAS, Max Conversions). |
| MUTATION | Vincula uma estratégia de portfólio a uma campanha. |
| REPORT | Lista todas as estratégias de lance de portfólio cadastradas na conta. |
Ferramenta | Tipo | Descrição |
| REPORT | Radar comparativo de leilão (7d vs 30d): detecta novos concorrentes e subida de lances. |
| REPORT | Relatório clássico de informações de leilão (impression share, overlap rate, outranking share). |
Ferramenta | Tipo | Descrição |
| REPORT | Audita integridade das tags de conversão; alerta ações primárias inativas ou sem disparos. |
| REPORT | Lista todas as ações de conversão configuradas e status de contagem. |
| MUTATION | Cria uma nova ação de conversão na conta. |
| MUTATION | Dispara conversão otimizada de leads (Enhanced Conversions) com hash SHA-256 nativo de dados pessoais. |
| MUTATION | Envio em lote de Enhanced Conversions para leads fechados offline. |
| MUTATION | Upload tradicional de conversões offline via GCLID. |
Ferramenta | Tipo | Descrição |
| CREATE | Cria estrutura completa de campanha Performance Max. |
| MUTATION | Injeta até 25 temas de pesquisa (Search Themes) em um Asset Group de PMax. |
| MUTATION | Vincula sinal de público-alvo (Audience Signal) ao Asset Group de PMax. |
| MUTATION | Vincula headlines, descrições e nome comercial ao Asset Group de PMax. |
| REPORT | Lista todos os sinais (Search Themes e Audiências) configurados no Asset Group. |
Ferramenta | Tipo | Descrição |
| CREATE | Cria campanha de Rede de Pesquisa padrão (criada pausada por segurança). |
| CREATE | Cria campanha, orçamento, grupo de anúncios, keywords e RSA em uma única chamada. |
| CREATE | Gera estrutura completa de múltiplos grupos de anúncios e keywords. |
| CREATE | Adiciona um novo grupo de anúncios a uma campanha. |
| MUTATION | Altera estado de veiculação da campanha ( |
Ferramenta | Tipo | Descrição |
| CREATE | Cria anúncio responsivo de pesquisa (RSA) com headlines e descrições. |
| MUTATION | Atualiza textos e títulos de um RSA existente. |
| CREATE | Faz upload de imagem para a biblioteca de assets da conta. |
Ferramenta | Tipo | Descrição |
| RESEARCH | Gera ideias de palavras-chave com volume de buscas e concorrência via Keyword Planner. |
| RESEARCH | Consulta volume de buscas histórico para uma lista específica de keywords. |
| RESEARCH | Previsão de cliques, impressões e custo para lista de keywords. |
| RESEARCH | Estimativa rápida de alcance para keywords e orçamento diário. |
| MUTATION | Adiciona palavras-chave compráveis a um grupo de anúncios (Broad, Phrase, Exact). |
| MUTATION | Ajusta o CPC individual de uma palavra-chave. |
| MUTATION | Pausa em lote keywords de baixa performance (possui modo |
| MUTATION | Substitui keywords de correspondência ampla para exata. |
| REPORT | Relatório de termos reais de pesquisa acionados pelos usuários. |
Ferramenta | Tipo | Descrição |
| MUTATION | Adiciona negativas diretamente a uma campanha. |
| CREATE | Cria lista de palavras-chave negativas compartilhada na conta. |
| MUTATION | Vincula lista compartilhada de negativas a uma campanha. |
| REPORT | Lista todas as listas de negativas compartilhadas existentes. |
Ferramenta | Tipo | Descrição |
| REPORT | Lista públicos-alvo e listas de remarketing da conta. |
| CREATE | Cria audiência personalizada combinando sinais de interesse e intenção. |
| CREATE | Cria audiência Customer Match a partir de lista de e-mails com hash SHA-256. |
| MUTATION | Vincula público-alvo a um grupo de anúncios com ajuste de lance opcional. |
| MUTATION | Desvincula/remove público-alvo ou critério restritivo de um grupo de anúncios. |
| MUTATION | Configura dimensão no grupo para Observação ( |
Ferramenta | Tipo | Descrição |
| MUTATION | Configura dimensão na campanha para observação ou segmentação. |
| MUTATION | Define segmentação geográfica da campanha (inclusão e exclusão de locais). |
| UTILITY | Busca códigos de cidades, estados e países aceitos pela API do Google Ads. |
| MUTATION | Ajusta lances por dispositivo (Mobile, Desktop, Tablet). |
| MUTATION | Configura horários e dias da semana para veiculação dos anúncios. |
| MUTATION | Configura os idiomas alvo da campanha. |
Ferramenta | Tipo | Descrição |
| MUTATION | Adiciona sitelinks com URLs e descrições a uma campanha. |
| MUTATION | Adiciona extensões de frase de destaque (callouts). |
| MUTATION | Adiciona extensões de snippets estruturados (marcas, serviços, tipos). |
| MUTATION | Adiciona extensão de chamada com número de telefone. |
| MUTATION | Adiciona extensão de tabela de preços e produtos/serviços. |
| MUTATION | Adiciona extensão de promoção com descontos e datas. |
| MUTATION | Remove uma extensão/asset vinculada a uma campanha. |
Ferramenta | Tipo | Descrição |
| REPORT | Performance comparativa detalhada por campanha. |
| REPORT | Quality Score, CPC médio, CTR e conversões por palavra-chave. |
| REPORT | Performance individual de anúncios e títulos mais eficientes. |
| REPORT | Performance e índice de força dos assets criativos. |
| REPORT | Segmentação de métricas por dispositivo (Computadores vs Celulares). |
| REPORT | Performance por localização geográfica real dos usuários. |
| REPORT | Distribuição de impressões, cliques e custo por hora do dia. |
| REPORT | Comparativo de distribuição: Google Search vs Search Partners vs Display. |
| REPORT | Métricas de conversão e custo por URL de destino. |
| REPORT | Desempenho segmentado por idade e gênero. |
Ferramenta | Tipo | Descrição |
| UTILITY | Valida autenticação e prontidão operacional do servidor com a API. |
| UTILITY | Lista todas as contas acessíveis sob o MCC ou autenticação direta. |
| SETUP | Inicia fluxo OAuth2 local para geração do refresh token. |
| CUSTOM | Executa queries GAQL customizadas com linter integrado (escape hatch seguro). |
| MUTATION | Aplica uma recomendação automática do Google Ads via resource_name. |
| MUTATION | Descarta uma recomendação do painel do Google Ads. |
| MUTATION | Cria, aplica e lista etiquetas para categorização de entidades. |
| UTILITY | Consulta faturas, métodos de pagamento e status da conta de faturamento. |
mcp_config.json)Para conectar ao servidor rodando na nuvem (Coolify):
{
"mcpServers": {
"google-ads": {
"type": "http",
"url": "https://SEU-DOMINIO/mcp",
"headers": {
"Authorization": "Bearer SEU_MCP_AUTH_TOKEN"
}
}
}
}claude_desktop_config.json){
"mcpServers": {
"google-ads": {
"url": "https://SEU-DOMINIO/sse?token=SEU_MCP_AUTH_TOKEN"
}
}
}{
"mcpServers": {
"google-ads": {
"type": "http",
"url": "http://127.0.0.1:8765/mcp"
}
}
}O repositório já possui configuração completa com Dockerfile otimizado:
Conecte o repositório https://github.com/octadigitalia/google-ads-mcp no Coolify.
Defina as variáveis de ambiente privadas no painel do Coolify:
MCP_AUTH_TOKEN: Token seguro para autenticação Bearer.
GOOGLE_ADS_DEVELOPER_TOKEN: Seu developer token do Google Ads.
GOOGLE_ADS_CLIENT_ID e GOOGLE_ADS_CLIENT_SECRET: Credenciais OAuth do Google Cloud.
GOOGLE_ADS_REFRESH_TOKEN: Refresh token gerado via setup.
GOOGLE_ADS_LOGIN_CUSTOMER_ID: ID da conta administradora (MCC) sem traços.
Clique em Deploy. O Coolify expõe automaticamente os endpoints com SSL Let's Encrypt gratuito e health check nativo em /health.
# 1. Clonar repositório
git clone https://github.com/octadigitalia/google-ads-mcp.git
cd google-ads-mcp-server
# 2. Criar e ativar venv
python -m venv .venv
.\.venv\Scripts\activate # Windows
# source .venv/bin/activate # Linux/macOS
# 3. Instalar dependências
pip install -r requirements.txt
# 4. Iniciar servidor
python start_worker.pyO projeto conta com suíte de testes unitários com mocks completos da Google Ads API:
# Executar todos os testes
python -m pytest tests/unit/test_new_tools.py -vPrevenção contra Gastos Acidentais: Campanhas criadas via IA entram com status PAUSED por padrão.
Segurança em Massa: Comandos de pausa em massa (bulk_pause_keywords) exigem confirmação ou operam com dry_run=True por padrão.
Resolução Amigável de Nomes: Todas as tools aceitam tanto o ID numérico quanto o Nome da Campanha / Grupo de Anúncios, resolvendo automaticamente via ResourceResolver.
Isolamento de Credenciais: Nenhuma chave ou token é versionado no Git; todas as credenciais residem no .env local ou no cofre de variáveis de ambiente do Coolify.
Distribuído sob a licença MIT. Desenvolvido pela equipe OctaDigital.
This server cannot be deployed
Google & Meta Ads management with 100+ tools. Audit, create, and optimize campaigns.
60+ Meta Ads tools for AI agents: audits, campaign management, audiences and CAPI tracking.
Run Google Ads and Meta Ads from ChatGPT or Claude: audit wasted spend, create and manage campaigns.
AI marketing agent for Google Ads, Meta, GA4, TikTok, LinkedIn, Shopify, HubSpot and more.
