# Claude ligado ao Meta Ads e ao Google Ads (via API)

Guia da Get Digital para a equipa de Tráfego. No fim, pedes ao Claude (no Cowork, no chat ou no Claude Code) coisas como *"faz o relatório semanal do cliente X com Meta e Google"* e ele vai buscar os números diretamente às contas, **pela API**.

**Porquê pela API e não pelo browser?** Se o Claude abrir o Google Ads ou o Gestor de Anúncios no browser, cada ecrã é uma captura de imagem e gasta muitos tokens (e é lento). Pela API recebe só os números que pediu, em texto. O mesmo relatório gasta uma fração dos tokens e fica pronto em segundos.

---

## Índice

1. [Como usar este guia](#1-como-usar-este-guia)
2. [Meta Ads (5 minutos, cada pessoa)](#2-meta-ads-5-minutos-cada-pessoa)
3. [Google Ads: configuração da agência, feita pelo Cowork (uma vez)](#3-google-ads-configuração-da-agência-feita-pelo-cowork-uma-vez)
4. [Google Ads: ligar ao Claude (2 minutos, cada pessoa)](#4-google-ads-ligar-ao-claude-2-minutos-cada-pessoa)
5. [Pedidos que funcionam (e gastam poucos tokens)](#5-pedidos-que-funcionam-e-gastam-poucos-tokens)
6. [Problemas comuns](#6-problemas-comuns)

---

## 1. Como usar este guia

**Toda a gente** faz a secção 2 (Meta Ads) e a secção 4 (Google Ads). São 2 minutos cada.

**Uma pessoa, uma única vez para a agência inteira**, faz a secção 3 com o **Cowork**: o Cowork faz o trabalho no teu Chrome (cria o projeto na Google Cloud, ativa a API, cria as credenciais e publica o servidor) e pára quando precisa de ti. Tu só aprovas, aceitas termos e fazes login.

**O que precisas para a secção 3:**
- A app do Claude no computador, com o **Cowork**.
- A extensão **Claude in Chrome** instalada e ligada (é o que deixa o Cowork usar o teu Chrome).
- No Chrome, a sessão iniciada na **conta Google de administrador da agência**: a que gere a conta de gestor (MCC) do Google Ads e pode criar projetos na Google Cloud.
- Um cartão para ativar a faturação da Google Cloud (se a agência ainda não tiver). O uso fica dentro dos escalões gratuitos ou custa cêntimos por mês.

**Como arrancar:** guarda este ficheiro numa pasta, abre o Cowork, dá-lhe acesso a essa pasta (ou anexa o ficheiro) e cola isto:

> Vais configurar o Google Ads da Get Digital para o Claude usar pela API. Lê o ficheiro **guia-trafego-claude.md** e segue a **secção 3**, fase a fase, no meu Chrome. Antes de começar, confirma comigo os dados da "Ficha" que só eu sei. Pára sempre nos pontos marcados com **[HUMANO]** e nunca escrevas segredos completos no chat.

---

## 2. Meta Ads (5 minutos, cada pessoa)

A Meta tem um conector oficial que já fala com a API do Marketing. Não é preciso configurar nada na Meta.

1. Abre a app do Claude e vai a **Personalizar › Conectores**.
2. Procura **Meta Ads**. Se aparecer, carrega em **Ligar** e salta para o passo 5.
3. Se não aparecer, carrega no **+** › **Adicionar conector personalizado**.
4. Preenche e carrega em **Adicionar**:
   - **Nome:** `Meta Ads`
   - **URL:** `https://mcp.facebook.com/ads`
5. Carrega em **Ligar**. No login do Facebook, entra com a conta que tem acesso ao Business Manager dos clientes e aceita as permissões.
6. Confirma numa conversa nova: *"Lista as contas de anúncios da Meta a que tenho acesso."*

> O Claude só vê as contas a que a tua conta do Facebook já tem acesso. Se falta um cliente, pede acesso no Business Manager.

> Plano Team: quem gere a conta do Claude pode adicionar o conector uma vez para todos (Definições da organização › Conectores). Cada pessoa só carrega em Ligar.

---

## 3. Google Ads: configuração da agência, feita pelo Cowork (uma vez)

### Como funciona (resumo para o humano)

A Google tem um servidor oficial que liga o Claude à **Google Ads API** ([googleads/google-ads-mcp](https://github.com/googleads/google-ads-mcp)). O Cowork só aceita conectores remotos (um endereço na internet), por isso vamos publicar esse servidor uma vez no **Google Cloud Run** da agência. Cada pessoa liga-se a ele com o seu login Google e vê só as contas a que já tem acesso.

Tudo é feito no browser: na Google Cloud Console e no **Cloud Shell** (o terminal que a Google dá dentro da consola, já com tudo instalado). Não é preciso instalar nada no Mac.

Tempo total: 30 a 45 minutos, a maior parte à espera de builds.

### Regras para o Cowork

1. Trabalha no Chrome do utilizador (Claude in Chrome), que já tem a sessão Google iniciada. Não peças palavras-passe.
2. Nos pontos **[HUMANO]**, pára, explica o que o utilizador tem de fazer e espera que ele confirme.
3. **Segredos** (developer token, Client Secret, chaves): nunca os escrevas completos no chat nem em ficheiros. Quando precisares de os referir, mostra só os últimos 4 caracteres. No Cloud Shell, introduz-os com `read -rs` (não aparecem no ecrã).
4. Mantém um ficheiro **ficha-google-ads.md** na pasta de trabalho com os valores **não secretos** da Ficha e uma lista das fases feitas. Se a sessão cair, retoma a partir daí.
5. No fim de cada fase faz a **verificação** indicada. Não avances se falhar: vê a secção 6 ou explica o erro ao utilizador.
6. A Google muda a interface com frequência. Se um botão não estiver onde o guia diz, procura a opção equivalente, diz ao utilizador o que encontraste e continua.
7. Antes de ações com custo ou difíceis de desfazer (ativar faturação, publicar o serviço), confirma com o utilizador.

### A Ficha: o que o Claude precisa e o que vai criar

| Dado | De onde vem | Secreto? |
|---|---|---|
| Email da conta de administrador | O utilizador diz | Não |
| A agência usa Google Workspace (`@agenciagetdigital.com`)? | O utilizador diz | Não |
| **ID da conta de gestor (MCC)** | Google Ads, topo do ecrã (10 dígitos, guardar sem traços) | Não |
| **Developer token** | Google Ads › Centro de API (fase A) | **Sim** |
| Nível de acesso do token | Google Ads › Centro de API | Não |
| **ID do projeto** Google Cloud | Criado na fase B (ex.: `getdigital-claude-ads`) | Não |
| Número do projeto | `gcloud projects describe` (fase C) | Não |
| Região | `europe-west1` | Não |
| **Client ID** OAuth | Criado na fase E | Não |
| **Client Secret** OAuth | Criado na fase E (só aparece uma vez) | **Sim** |
| **URL do serviço** | `https://google-ads-mcp-NUMERO_DO_PROJETO.europe-west1.run.app` | Não |
| URI de redirecionamento | URL do serviço + `/auth/callback` | Não |
| **URL do conector** (para a equipa) | URL do serviço + `/mcp` | Não |
| Chave JWT e chave de encriptação | Geradas no Cloud Shell (fase F), nunca saem de lá | **Sim** |

---

### Fase A: Developer token (Google Ads)

1. Abre [ads.google.com](https://ads.google.com) e entra na **conta de gestor (MCC)** da agência (não numa conta de cliente). Aponta o **ID da conta de gestor**.
2. Vai a **Administrador › Centro de API** (em interfaces antigas: **Ferramentas e definições › Configuração › Centro de API**).
3. **[HUMANO]** Se ainda não houver token, o formulário pede:
   - Email de contacto da API: o email de administrador.
   - Site da empresa: `https://agenciagetdigital.com` (confirma com o utilizador).
   - Utilização prevista (pode ser esta): *"Internal reporting for our agency: read-only access to campaign performance of the client accounts we manage, used by our team through an AI assistant to build weekly reports."*
   - O utilizador aceita os termos da API.
4. Aponta o **developer token** (secreto) e o **nível de acesso** que aparece.

**Verificação:** existe um developer token e o nível de acesso não é "Conta de teste". Se for "Conta de teste" (só funciona em contas de teste), pede o acesso **Explorer** ou **Básico** no mesmo ecrã e avisa o utilizador de que a Google pode demorar uns dias a aprovar. Podes continuar as fases seguintes entretanto.

### Fase B: Projeto na Google Cloud

1. Abre [console.cloud.google.com/projectcreate](https://console.cloud.google.com/projectcreate).
2. Nome: `Claude Google Ads`. Confirma o **ID do projeto** sugerido (ex.: `getdigital-claude-ads`); se estiver ocupado, aceita a variação que a Google propõe. Organização: a da agência, se existir.
3. Cria e espera que fique pronto.
4. **[HUMANO]** Se a consola pedir para associar uma **conta de faturação**, o utilizador escolhe ou cria uma (com cartão). Sem faturação o Cloud Run não funciona.

**Verificação:** o seletor de projetos no topo mostra o novo projeto e em [Faturação](https://console.cloud.google.com/billing/linkedaccount) aparece uma conta associada.

### Fase C: Cloud Shell, APIs e Firestore

1. Abre o Cloud Shell: [shell.cloud.google.com](https://shell.cloud.google.com/?show=terminal) (ou o ícone **>_** no topo da consola). **[HUMANO]** Na primeira vez, o utilizador autoriza o Cloud Shell.
2. Cola, trocando o ID do projeto:

```bash
export PROJECT_ID=getdigital-claude-ads
export REGION=europe-west1
gcloud config set project $PROJECT_ID
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
export BASE_URL=https://google-ads-mcp-$PROJECT_NUMBER.$REGION.run.app
echo "Número do projeto: $PROJECT_NUMBER"; echo "URL do serviço: $BASE_URL"

gcloud services enable googleads.googleapis.com run.googleapis.com cloudbuild.googleapis.com \
  artifactregistry.googleapis.com firestore.googleapis.com iamcredentials.googleapis.com

gcloud firestore databases create --location=$REGION
```

3. Aponta na Ficha o **número do projeto** e o **URL do serviço**.

**Verificação:** `gcloud services list --enabled | grep -E "googleads|run|cloudbuild|firestore"` mostra as 4 APIs, e `gcloud firestore databases list` mostra a base de dados `(default)`.

> Se o Cloud Shell fechar a meio, as variáveis perdem-se. Volta a correr as 5 primeiras linhas (até ao `echo`) antes de continuar.

### Fase D: Ecrã de consentimento OAuth

1. Abre `https://console.cloud.google.com/auth/overview?project=ID_DO_PROJETO` e carrega em **Começar** (Get started).
2. **Informações da app:** nome `Claude Google Ads (Get Digital)` e email de suporte (o de administrador).
3. **Público (Audience):**
   - Se a agência usa Google Workspace: **Interno**. Só emails `@agenciagetdigital.com` conseguem entrar e não é preciso verificação da Google. É a opção certa.
   - Se não usa Workspace: **[HUMANO]** só existe **Externo**. Nesse caso, depois de criar, vai a **Público** e carrega em **Publicar app** (em modo "Teste" os logins caducam ao fim de 7 dias). A Google pode mostrar um aviso de "app não verificada" no login: é esperado para uso interno. Avisa o utilizador.
4. **Dados de contacto:** o email de administrador. Aceita a política e cria.
5. Em **Acesso a dados** (Data access), adiciona os âmbitos `openid`, `.../auth/userinfo.email`, `.../auth/userinfo.profile` e `https://www.googleapis.com/auth/adwords`, e guarda.

**Verificação:** a página **Público** mostra o tipo escolhido e **Acesso a dados** mostra o âmbito `adwords`.

### Fase E: Cliente OAuth

1. Abre `https://console.cloud.google.com/auth/clients/create?project=ID_DO_PROJETO`.
2. Tipo: **Aplicação Web**. Nome: `Claude Google Ads`.
3. Em **URIs de redirecionamento autorizados**, adiciona exatamente: **URL do serviço** + `/auth/callback` (ex.: `https://google-ads-mcp-123456789012.europe-west1.run.app/auth/callback`).
4. Cria. Aparece o **Client ID** e o **Client Secret**.
   - Aponta o Client ID na Ficha.
   - O Client Secret **só aparece desta vez**: descarrega o JSON (guardado só no computador do utilizador) e usa-o já na fase F. Não o escrevas no chat.

**Verificação:** a lista de clientes mostra `Claude Google Ads` com o URI de redirecionamento certo.

### Fase F: Publicar o servidor no Cloud Run

**[HUMANO]** Confirma com o utilizador antes de publicar (cria recursos que podem ter custo, mínimo).

No Cloud Shell (com as variáveis da fase C):

```bash
# dados (o token e o secret pedem-se escondidos: cola e carrega Enter)
export MCC_ID=1234567890          # ID da conta de gestor, sem traços
export CLIENT_ID=COLA_O_CLIENT_ID.apps.googleusercontent.com
read -rsp "Developer token: " DEV_TOKEN; echo
read -rsp "Client Secret: " CLIENT_SECRET; echo
export JWT_KEY=$(openssl rand -hex 32) ENC_KEY=$(openssl rand -hex 32)
export SA=$PROJECT_NUMBER-compute@developer.gserviceaccount.com

# permissões da conta de serviço (build e Firestore)
for ROLE in roles/cloudbuild.builds.builder roles/datastore.user roles/logging.logWriter; do
  gcloud projects add-iam-policy-binding $PROJECT_ID --member=serviceAccount:$SA --role=$ROLE --condition=None --quiet >/dev/null
done

# código oficial da Google + suporte para guardar os logins no Firestore
rm -rf google-ads-mcp && git clone https://github.com/googleads/google-ads-mcp.git && cd google-ads-mcp
sed -i 's|RUN uv pip install --system \.|RUN uv pip install --system ".[firestore]"|' Dockerfile
grep "uv pip install" Dockerfile    # tem de mostrar: RUN uv pip install --system ".[firestore]"

# construir a imagem
gcloud artifacts repositories create mcp-servers --repository-format=docker --location=$REGION 2>/dev/null
gcloud builds submit --tag $REGION-docker.pkg.dev/$PROJECT_ID/mcp-servers/google-ads-mcp:latest .

# publicar
gcloud run deploy google-ads-mcp \
  --image $REGION-docker.pkg.dev/$PROJECT_ID/mcp-servers/google-ads-mcp:latest \
  --region $REGION --platform managed --allow-unauthenticated --min-instances=0 \
  --set-env-vars="GOOGLE_PROJECT_ID=$PROJECT_ID,GOOGLE_ADS_DEVELOPER_TOKEN=$DEV_TOKEN,GOOGLE_ADS_LOGIN_CUSTOMER_ID=$MCC_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=$CLIENT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=$CLIENT_SECRET,GOOGLE_ADS_MCP_BASE_URL=$BASE_URL,GOOGLE_ADS_MCP_JWT_SIGNING_KEY=$JWT_KEY,GOOGLE_ADS_MCP_STORAGE_TYPE=firestore,GOOGLE_ADS_MCP_STORAGE_ENCRYPTION_KEY=$ENC_KEY,FASTMCP_HOST=0.0.0.0"
```

> O `--allow-unauthenticated` é normal: o endereço é público, mas ninguém usa o servidor sem fazer login com uma conta Google com acesso ao Google Ads (e, com o público "Interno", só emails da agência).

**Verificação:**

```bash
curl -s $BASE_URL/.well-known/oauth-authorization-server | head -c 400; echo
```

- Tem de aparecer um JSON com `"issuer"` igual ao **URL do serviço** da Ficha. Se aparecer, o servidor está no ar e o endereço do login (`/auth/callback`) bate certo com o da fase E.
- Se der erro ou página vazia: o Cloud Run pode ter dado outro endereço ao serviço. Vê-o com `gcloud run services describe google-ads-mcp --region $REGION --format='value(status.url)'`, usa esse como URL do serviço (`gcloud run services update google-ads-mcp --region $REGION --update-env-vars=GOOGLE_ADS_MCP_BASE_URL=NOVO_URL`), atualiza o URI de redirecionamento na fase E e a Ficha, e repete o `curl`.
- Se continuar a falhar, vê os registos: `gcloud run services logs read google-ads-mcp --region $REGION --limit 50`.

### Fase G: Primeiro teste

1. **[HUMANO]** O utilizador adiciona o conector na app do Claude (secção 4) com o **URL do conector** (URL do serviço + `/mcp`) e faz login com a conta de administrador.
2. Numa conversa nova, testa:
   - *"Usa o Google Ads (Get Digital) e lista as contas a que tenho acesso, com o nome de cada uma."*
   - *"Na conta [um cliente], mostra o investimento, cliques e conversões dos últimos 7 dias, por campanha."*

**Verificação:** a lista de contas aparece e a consulta devolve números que batem certo com o Google Ads.

3. Atualiza a **ficha-google-ads.md** com o URL do conector e a data, e diz ao utilizador para o enviar à equipa com a secção 4 deste guia.

### Segurança

- O developer token, o Client Secret e as chaves ficam **só no Cloud Run**. Não vão para o Slack, para este guia nem para os computadores da equipa.
- Para tirar o acesso a alguém, basta retirar-lhe o acesso no Google Ads ou na conta Google da agência.
- O servidor oficial só faz **consultas** (lista contas, lê métricas e definições). Não cria nem altera campanhas.

---

## 4. Google Ads: ligar ao Claude (2 minutos, cada pessoa)

Precisas do **URL do conector** que o responsável te enviou (acaba em `/mcp`).

1. Na app do Claude: **Personalizar › Conectores › + › Adicionar conector personalizado**.
2. Preenche e carrega em **Adicionar**:
   - **Nome:** `Google Ads (Get Digital)`
   - **URL:** o URL do conector.
3. Carrega em **Ligar**. No login da Google, entra com **o teu email da agência** e aceita.
4. Confirma numa conversa nova: *"Lista as contas do Google Ads a que tenho acesso, com o nome de cada uma."*

> Cada pessoa entra com a sua conta Google, por isso o Claude só vê as contas Google Ads a que tu já tens acesso.

---

## 5. Pedidos que funcionam (e gastam poucos tokens)

No **Cowork**, o Claude trabalha sozinho numa tarefa mais longa: vai buscar os dados pela API, faz as contas e entrega um ficheiro (Excel, PDF, documento).

**Para gastar poucos tokens:**
- Diz sempre o **cliente**, o **período** e as **métricas** que queres. Pedidos vagos ("mostra tudo") trazem dados a mais.
- Pede dados **agregados** (por campanha, por semana) em vez de linha a linha.
- Para comparar, pede os dois períodos no mesmo pedido.
- Se o relatório se repete, guarda o pedido e reutiliza-o.

**Relatório semanal**
> Faz o relatório semanal do cliente **[nome]** de **segunda passada a domingo**: Meta Ads e Google Ads lado a lado, por campanha, com investimento, impressões, cliques, CTR, CPC, conversões, custo por conversão e ROAS, e a comparação com a semana anterior. No fim, 3 pontos do que correu bem, 3 a melhorar e 3 ações para a próxima semana. Entrega em Excel.

**Diagnóstico rápido**
> No Google Ads do cliente **[nome]**, quais as 10 campanhas com mais gasto nos últimos 30 dias e qual o custo por conversão de cada uma? Assinala as que estão acima da média da conta.

**Criativos da Meta**
> Na conta Meta do cliente **[nome]**, mostra os 10 anúncios com melhor e os 10 com pior custo por resultado nos últimos 14 dias, com o texto e o tipo de criativo de cada um.

**Palavras-chave**
> No Google Ads do cliente **[nome]**, que termos de pesquisa gastaram mais de 20€ nos últimos 30 dias sem nenhuma conversão? Sugere palavras-chave negativas.

**Ritmo de gasto de todos os clientes**
> Para todas as contas Google Ads e Meta a que tenho acesso, faz uma tabela com o investimento do mês até hoje e o ritmo de gasto diário. Assinala quem está a gastar demais ou de menos face ao mês passado.

**Cuidados**
- Confirma os números importantes na plataforma antes de os mandar ao cliente.
- O conector da Meta pode fazer alterações (pausar, mudar orçamentos). O Claude pede sempre confirmação antes: **lê bem antes de aceitar**. O do Google Ads só lê.

---

## 6. Problemas comuns

**Todos**
- **Não vejo o conector no Cowork.** Em Personalizar › Conectores tem de estar **Ligado** (não só adicionado). Abre uma conversa nova depois de ligar.
- **Falta um cliente.** O Claude só vê o que a tua conta já vê. Pede acesso no Business Manager (Meta) ou na conta de gestor (Google Ads).
- **Pede para fazer login outra vez.** Normal de vez em quando: em Personalizar › Conectores, carrega em Ligar e entra outra vez.
- **Os números não batem certo.** Verifica o período e o fuso horário da conta, se as conversões são as mesmas colunas, e lembra-te de que as últimas 24 a 48 horas ainda podem mudar.

**Google Ads (para quem configurou)**
- **"DEVELOPER_TOKEN_NOT_APPROVED" ou erro de token.** O token está em "Conta de teste". Pede o acesso Explorer ou Básico no Centro de API.
- **"USER_PERMISSION_DENIED".** O login não tem acesso à conta, ou o `MCC_ID` está errado (tem de ser o ID da conta de gestor, sem traços).
- **"redirect_uri_mismatch" no login.** O URI na fase E tem de ser exatamente o URL do serviço + `/auth/callback`. O erro mostra o endereço pedido: copia-o para o cliente OAuth.
- **"app não permitida" / "acesso bloqueado" no login.** Com público "Interno", só entram emails da agência. Usa o email `@agenciagetdigital.com`.
- **O `gcloud builds submit` falha por permissões.** Volta a correr o bloco "permissões da conta de serviço" da fase F e espera 1 minuto.
- **O deploy falha com "allUsers" / política da organização.** A organização Google Workspace impede serviços públicos (política "Domain restricted sharing"). Um administrador do Workspace tem de abrir uma exceção para este projeto em IAM e administração › Políticas da organização.
- **Os logins perdem-se quando o serviço reinicia.** A imagem foi construída sem o Firestore: confirma a linha `".[firestore]"` no Dockerfile e repete o build e o deploy.

---

Feito por Tiago Mendes · Get Digital