# 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:

```json
{ "preset": "LAST_30_DAYS" }
```

```json
{ "lastDays": 45 }
```

```json
{ "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

```mermaid
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

```bash
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:

```bash
pnpm check
```

## Configuração Google

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

```text
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:

```bash
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:

```bash
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`:

```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:

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

## Conectar ao Claude

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

```text
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

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