Como conectar Meta Ads, Google Ads, GA4 e TikTok Ads ao Claude Code ou Codex

01O que você precisa

• Um computador com macOS, Windows ou Linux.
• Uma assinatura de agente: Claude Pro ou Max (para o Claude Code) ou ChatGPT Plus ou Pro (para o Codex). O plano gratuito do Claude não inclui o Claude Code.
• Acesso de administrador às contas que vai conectar: o portfólio empresarial (Business Manager) do Meta, a conta do Google Ads, a propriedade do GA4 e a conta do TikTok Ads.
• Python 3 e Git. No Mac, rode python3 --version no Terminal: se ele oferecer instalar as "ferramentas de linha de comando", aceite, que isso já instala os dois. No Windows, instale o Python (marque "Add python.exe to PATH") e o Git, e use py onde este guia diz python3.

02Instale o Claude Code ou o Codex

Escolha um dos dois (ou os dois: a skill funciona igual). Abra o Terminal (no Windows, o PowerShell) e rode:

Claude Code

curl -fsSL https://claude.ai/install.sh | bash

irm https://claude.ai/install.ps1 | iex

Feche e abra o terminal, rode claude e faça login com sua conta do Claude quando o navegador abrir. Para conferir a instalação: claude --version.

Codex

curl -fsSL https://chatgpt.com/codex/install.sh | sh

npm install -g @openai/codex

Rode codex e escolha Sign in with ChatGPT.

03Instale o Orca

O Orca é um app gratuito e de código aberto para rodar agentes de IA lado a lado. Cada tarefa ganha a própria cópia isolada do projeto (um worktree do Git), com terminal e navegador próprios. Ele usa a assinatura que você já tem, sem login extra, e é onde eu deixo um agente por cliente rodando ao mesmo tempo.

brew install --cask stablyai/orca/orca

Sem Homebrew, ou no Windows e no Linux, baixe o instalador em onorca.dev/download.

Crie a pasta do projeto

O Orca trabalha com repositórios Git. Crie uma pasta para o cliente (ou para você) e transforme em repositório com um primeiro commit vazio:

mkdir -p ~/clientes/minha-marca && cd ~/clientes/minha-marca
git init
git commit --allow-empty -m "inicio"

Abra no Orca

1. Clique em Add Repo na barra lateral e escolha a pasta que você criou.
2. Clique no + ao lado do nome do repositório, dê um nome para a tarefa (por exemplo connect-ads) e mantenha a base sugerida.
3. No terminal que abre, escolha o agente no seletor: Claude Code ou Codex. Ele inicia já dentro da pasta da tarefa.

04Instale a skill

Skill é um pacote de instruções e scripts que o agente carrega quando precisa. A connect-ads é a versão aberta do processo que eu uso: ela confere o que já existe, te guia só pelo que falta, guarda as chaves no .env e testa cada conexão.

Baixe o .zip (é só deixar seu e-mail no quadro do início) e, na pasta onde ele foi salvo (normalmente Downloads), rode:

cd ~/Downloads
mkdir -p ~/.claude/skills ~/.agents/skills
unzip -o connect-ads.zip -d ~/.claude/skills
unzip -o connect-ads.zip -d ~/.agents/skills

cd $HOME\Downloads
Expand-Archive connect-ads.zip "$HOME\.claude\skills" -Force
Expand-Archive connect-ads.zip "$HOME\.agents\skills" -Force

A primeira pasta é onde o Claude Code procura skills, a segunda é a do Codex. Se só usa um deles, pode rodar só a linha dele. Se o agente já estava aberto, feche e abra de novo para ele enxergar a skill.

05Peça para o agente conectar

No terminal do Orca, com o agente aberto, escreva:

Use a skill connect-ads para conectar minhas contas de anúncio.

O agente cria o .env, o .gitignore e a pasta scripts/, pergunta quais plataformas você usa e o que já existe em cada uma, e te leva por um passo de cada vez. Você faz os cliques no painel de cada plataforma e cola de volta o que ele pedir.

As seções abaixo são o mesmo roteiro, para você saber de antemão o que vai fazer (ou fazer sozinho, se preferir).

06Meta Ads

O caminho mais estável é um usuário do sistema: um "robô" dentro do seu portfólio empresarial, com token que não expira e acesso só ao que você atribuir.

1. Portfólio empresarial: abra business.facebook.com/settings. O ID aparece na URL, depois de business_id=.
2. App: em developers.facebook.com/apps, clique em Criar app, escolha o caso de uso Outro e o tipo Empresa, dê o nome do projeto e vincule ao seu portfólio. No painel do app, adicione o produto API de Marketing. App ID e chave secreta ficam em Configurações do app > Básico. Pode deixar o app em modo de desenvolvimento: para contas do seu próprio portfólio, funciona.
3. Usuário do sistema: em Configurações do negócio > Usuários > Usuários do sistema, clique em Adicionar, dê um nome e escolha a função Admin.
4. Atribua os ativos: no usuário criado, use Atribuir ativos e dê controle total sobre a conta de anúncios, a página, o pixel (conjunto de dados) e o app.
5. Gere o token: clique em Gerar novo token, escolha o app, validade Nunca e marque as permissões ads_read, ads_management, business_management, pages_read_engagement e read_insights. O token aparece uma única vez: cole no .env como META_ACCESS_TOKEN.
6. IDs: o ID da conta de anúncios vai no formato act_ + números. Os IDs da página e do pixel são opcionais.

Teste:

python3 scripts/meta_test.py

Se aparecer o nome do usuário do sistema, a conta e o gasto dos últimos 7 dias, está conectado. Erro 190 é token inválido. Erro 100 ou 200 em algum ativo quase sempre significa que ele não foi atribuído ao usuário do sistema.

07Google Cloud (base para Google Ads e GA4)

Google Ads e GA4 usam o mesmo projeto e o mesmo login. Você faz isto uma vez e reaproveita para todos os clientes.

1. Em console.cloud.google.com, crie um projeto (por exemplo "Ads Operator").
2. Em APIs e serviços > Biblioteca, ative a Google Ads API, a Google Analytics Admin API e a Google Analytics Data API.
3. Em Google Auth Platform, configure a tela de consentimento: nome neutro, seu e-mail, público Externo. Depois, em Público-alvo, clique em Publicar app para o status ficar Em produção.
4. Em Clientes, crie um cliente OAuth do tipo App para computador. Copie o ID e a chave secreta para GOOGLE_CLIENT_ID e GOOGLE_CLIENT_SECRET.

08Google Ads

1. Abra console.cloud.google.com/google/ads-apis/overview no mesmo projeto. Ativar a API dá o nível Teste, que só enxerga contas de teste. Expanda Upgrade access level e clique em Apply for access para pedir o Explorer. A aprovação costuma ser automática. O Explorer libera 2.880 operações por dia em contas reais, bem mais do que relatórios consomem.
2. Copie o ID de 10 dígitos que aparece no topo do Google Ads para GOOGLE_ADS_CUSTOMER_ID.
3. Se você acessa a conta por uma MCC (conta de administrador), coloque o ID da MCC em GOOGLE_ADS_LOGIN_CUSTOMER_ID e confira, na conta do cliente, que o vínculo foi aceito. Se não usa MCC, deixe vazio.
4. Faça o login do Google para o Ads. O navegador abre: entre com o usuário que tem acesso à conta (ou à MCC).

python3 scripts/google_oauth.py --for ads
python3 scripts/google_ads_test.py

O teste lista as campanhas dos últimos 7 dias. Se aparecer USER_PERMISSION_DENIED, o usuário do Google não alcança a conta, ou o vínculo com a MCC não foi aceito. Se aparecer CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION, o projeto ainda está no nível Teste (passo 1).

09GA4

1. Garanta que o seu usuário do Google tem pelo menos acesso de Leitor na propriedade (GA4 > Administrador > Gerenciamento de acesso à propriedade).
2. Copie o ID de métricas G-... (Administrador > Fluxos de dados) para GA4_MEASUREMENT_ID.
3. Rode o login, a busca da propriedade e o teste:

python3 scripts/google_oauth.py --for ga4
python3 scripts/ga4_find_property.py
python3 scripts/ga4_test.py

O teste mostra usuários, sessões e os eventos de e-commerce da última semana. Se aparecerem mais compras do que inícios de checkout, o rastreamento do checkout provavelmente está quebrado. Isso não é erro de conexão: é a primeira coisa que vale corrigir.

10TikTok Ads

A API do TikTok exige um app de desenvolvedor aprovado. Peça logo, porque a análise pode levar alguns dias.

1. No TikTok Ads Manager, copie o ID da conta de anúncios (só números) para TIKTOK_ADVERTISER_ID.
2. Em business-api.tiktok.com/portal, cadastre-se como desenvolvedor e crie um app em My Apps. Preencha nome e descrição e, como URL de redirecionamento, use o seu site: o código só precisa aparecer na barra de endereço. Marque as permissões de conta de anúncios, de anúncios (leitura) e de relatórios, e envie para análise.
3. Com o app aprovado, copie o App ID e o Secret para TIKTOK_APP_ID e TIKTOK_APP_SECRET.
4. Abra a Advertiser authorization URL que aparece na página do app, escolha as contas e confirme. O TikTok volta para o seu site com auth_code=... na barra de endereço.
5. Rode o script abaixo e cole o endereço inteiro. O código vale uma vez só, por cerca de uma hora.

python3 scripts/tiktok_oauth.py
python3 scripts/tiktok_test.py

Se o TikTok informar uma data de validade, o script salva em TIKTOK_TOKEN_EXPIRES_AT. Anote: quando o token vence, as automações param sem aviso.

11Segurança

• As chaves ficam no .env, no seu computador. A skill coloca o .env no .gitignore antes de gravar qualquer chave e nunca mostra os valores no chat. Os scripts só falam com as APIs das próprias plataformas.
• Nunca mande o .env para o GitHub, para um grupo ou para outra IA.
• Para revogar um acesso: no Meta, exclua ou revogue o token do usuário do sistema. No Google, remova o app em myaccount.google.com/permissions. No TikTok, desautorize o app no Business Center.
• Worktrees novos não levam o .env, justamente porque ele fica fora do Git. Se abrir outra tarefa no Orca para o mesmo cliente, copie o .env para a pasta dela.

12O que pedir depois

Com as contas conectadas, o agente lê os dados direto da fonte. Alguns pedidos que eu uso no dia a dia:

Compare gasto, CPA e ROAS da última semana entre Meta e Google Ads e me diga onde está o desperdício.

Liste as campanhas que gastaram nos últimos 14 dias sem gerar conversão.

Cruze as compras do GA4 com as conversões que Meta e Google reportam e me mostre a diferença.

Monte um relatório diário com os resultados de ontem e salve em relatorios/.