Google Ads MCP para Cloudflare Workers

Servidor MCP remoto, somente leitura, para conectar o Google Ads ao Claude. Esta implementação usa TypeScript, Cloudflare Workers, OAuth 2.1, Streamable HTTP e a API REST oficial do Google Ads.

O projeto foi refeito a partir das capacidades do google-ads-mcp-server; ele não depende de Python, Uvicorn, gRPC ou de um processo persistente.

Capacidades

• Contas configuradas por alias.
• Relatórios de conta, campanha, grupo, anúncio, asset e conversão.
• Palavras-chave e termos de pesquisa.
• Quebras por data, dispositivo, rede, dia da semana e hora.
• Granularidade consolidada, diária, semanal e mensal.
• Comparação de períodos com variação percentual.
• Alertas de custo, conversões, CPA e ROAS.
• Pesquisa de volume e ideias de palavras-chave.
• GAQL avançada somente leitura, com limite de linhas.
• OAuth 2.1 para o Claude, login Google, consentimento explícito e allowlist de e-mails.

Períodos

As ferramentas aceitam exatamente um dos formatos abaixo:

{ "preset": "LAST_30_DAYS" }

{ "lastDays": 45 }

{ "startDate": "2026-07-01", "endDate": "2026-07-31" }

lastDays igual a 7, 14 ou 30 gera DURING LAST_X_DAYS. Outros valores geram um intervalo BETWEEN, evitando presets que não existem no GAQL. Períodos explícitos sempre usam BETWEEN.

Assim como o Google Ads, LAST_X_DAYS termina ontem e não inclui o dia atual.

Arquitetura

flowchart LR
    Claude[Claude] -->|MCP Streamable HTTP + OAuth 2.1| Worker[Cloudflare Worker]
    Worker -->|OAuth refresh token| GoogleOAuth[Google OAuth]
    Worker -->|REST + GAQL| GoogleAds[Google Ads API]
    Worker --> KV[Cloudflare KV: estados OAuth]
    Worker --> Secrets[Cloudflare Secrets]

O endpoint MCP é /mcp. /health verifica o processo e /ready informa se os principais Secrets estão presentes.

Pré-requisitos

• Node.js 22 ou superior e pnpm.
• Conta Cloudflare com Workers e KV.
• Developer Token aprovado para a Google Ads API.
• Google Ads API ativada no mesmo projeto Google Cloud que emitiu o cliente OAuth usado por GOOGLE_ADS_CLIENT_ID.
• OAuth Client ID, Client Secret e Refresh Token com o escopo https://www.googleapis.com/auth/adwords.
• Um OAuth Web Client para autenticar as pessoas que poderão conectar o MCP ao Claude.

Os clientes OAuth do acesso ao MCP e do Google Ads podem pertencer ao mesmo projeto Google, mas têm funções diferentes. Em produção, prefira clientes separados.

Desenvolvimento local

pnpm install
cp .dev.vars.example .dev.vars
pnpm dev

O cookie OAuth usa o prefixo seguro __Host-; portanto, o fluxo de login completo deve ser validado no endereço HTTPS publicado. As funções puras e a integração REST simulada podem ser testadas localmente:

pnpm check

Configuração Google

Crie um OAuth Client do tipo Web Application para o login do conector. Cadastre como redirect URI:

https://SEU-WORKER.SEU-SUBDOMINIO.workers.dev/callback

O e-mail autenticado precisa estar em ALLOWED_GOOGLE_EMAILS. Essa autenticação controla quem pode usar o MCP; as consultas ao Google Ads utilizam o Refresh Token configurado no Worker.

Deploy no Cloudflare

1. Crie o namespace KV:

pnpm exec wrangler kv namespace create OAUTH_KV

2. Substitua REPLACE_WITH_KV_NAMESPACE_ID em wrangler.jsonc pelo ID retornado.

3. Defina os Secrets:

pnpm exec wrangler secret put GOOGLE_OAUTH_CLIENT_ID
pnpm exec wrangler secret put GOOGLE_OAUTH_CLIENT_SECRET
pnpm exec wrangler secret put COOKIE_ENCRYPTION_KEY
pnpm exec wrangler secret put GOOGLE_ADS_DEVELOPER_TOKEN
pnpm exec wrangler secret put GOOGLE_ADS_CLIENT_ID
pnpm exec wrangler secret put GOOGLE_ADS_CLIENT_SECRET
pnpm exec wrangler secret put GOOGLE_ADS_REFRESH_TOKEN
pnpm exec wrangler secret put GOOGLE_ADS_LOGIN_CUSTOMER_ID
pnpm exec wrangler secret put ACCOUNTS_JSON

Gere COOKIE_ENCRYPTION_KEY com ao menos 32 bytes aleatórios. Nunca reutilize tokens ou segredos como chave de cookie.

Exemplo de ACCOUNTS_JSON:

{
  "Cliente A": "123-456-7890",
  "Cliente B": "987-654-3210"
}

4. Edite ALLOWED_GOOGLE_EMAILS em wrangler.jsonc. Vários e-mails devem ser separados por vírgula.

5. Valide e publique:

pnpm check
pnpm exec wrangler deploy --dry-run
pnpm deploy

Conectar ao Claude

No Claude, abra as configurações de conectores personalizados e informe:

https://SEU-WORKER.SEU-SUBDOMINIO.workers.dev/mcp

O Claude fará o registro dinâmico do cliente, abrirá o consentimento do MCP e, em seguida, o login Google. A callback do cliente MCP é administrada pelo protocolo; a callback Google continua sendo /callback no Worker.

Ferramentas MCP

Ferramenta	Finalidade
google_ads_list_accounts	Contas e aliases disponíveis
google_ads_account_report	Visão geral da conta
google_ads_campaign_report	Campanhas e canais
google_ads_ad_group_report	Grupos de anúncios
google_ads_ad_report	Anúncios e URLs finais
google_ads_asset_report	Assets e classificação de desempenho
google_ads_conversion_report	Ações e categorias de conversão
google_ads_keyword_report	Keywords, correspondência e quality score
google_ads_search_terms	Termos reais pesquisados
google_ads_dimension_report	Data, dispositivo, rede, dia ou hora
google_ads_compare_periods	Comparação e variação percentual
google_ads_performance_insights	Anomalias e tendências recentes
google_ads_keyword_ideas	Volume e ideias do Keyword Planner
google_ads_run_gaql	Consulta GAQL avançada de leitura

Segurança e operação

• Nenhuma ferramenta altera campanhas.
• GAQL livre aceita somente uma instrução iniciada por SELECT.
• Respostas têm limite configurável entre 1 e 5.000 linhas.
• IDs de contas e campanhas são validados antes de entrar em consultas.
• Tokens nunca são devolvidos nas respostas MCP.
• Estados OAuth expiram após dez minutos e são consumidos uma única vez.
• Restrinja o Worker adicionalmente com regras de rate limiting do Cloudflare/WAF.
• Use observabilidade sem registrar headers Authorization, refresh tokens ou payloads de Secrets.
• Revise GOOGLE_ADS_API_VERSION antes da descontinuação da versão configurada.

Comandos de qualidade

pnpm typecheck
pnpm test
pnpm exec wrangler deploy --dry-run