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

Crie o namespace KV:

pnpm exec wrangler kv namespace create OAUTH_KV

Substitua REPLACE_WITH_KV_NAMESPACE_ID em wrangler.jsonc pelo ID retornado.
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"
}

Edite ALLOWED_GOOGLE_EMAILS em wrangler.jsonc. Vários e-mails devem ser separados por vírgula.
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