Configurar Google Ads API — Ratos de IA
🐀
Ratos de IA · Ads Ratos
Configurar Google Ads API
Progresso
0 de 7

Tudo que tu precisa pra conectar a skill de Google Ads no Claude Code. Tu vai fazer a maioria das coisas conversando com o Claude, e só precisa ir no Google pra criar as credenciais. Leva uns 20 a 30 minutos.

Antes de começar
1
Passo 1 de 7

Criar conta MCC (se ainda não tem)

A skill precisa de uma conta de gerenciamento (MCC) pra se conectar na API. Se tu já tem uma, pula pro passo 2. Se só tem uma conta normal de Google Ads, é rapidinho criar.

Criando a MCC
1
Acessa ads.google.com/home/tools/manager-accounts/ e clica em "Criar conta de gerenciamento"
2
Faz login com a mesma conta Google que já tem acesso ao Google Ads
3
Escolhe um nome pro gerenciador (tipo "Minha Agência" ou o nome da tua empresa)
4
Seleciona "Gerenciar minhas próprias contas"
5
Escolhe país, fuso horário e moeda. Clica em "Enviar"
6
Pronto, MCC criada!
Vincular tua conta existente
1
No MCC que acabou de criar, clica no + (Contas > Performance > botão azul "+")
2
Seleciona "Vincular conta existente" e digita o Customer ID da tua conta normal (aquele XXX-XXX-XXXX que aparece no canto superior do Google Ads)
3
Um convite é enviado. Vai na tua conta normal de Google Ads, em Configurações > Acesso à conta, e aceita o convite do gerenciador
💡 A MCC é uma conta separada que gerencia outras contas. Ela não substitui tua conta de anúncios. Pensa nela como uma "pasta" que agrupa contas.
2
Passo 2 de 7

Criar projeto no Google Cloud Console

Agora tu precisa criar um projeto no Google Cloud. É lá que ficam as credenciais (Client ID e Client Secret) que a API usa pra se autenticar.

Criando o projeto
1
Acessa console.cloud.google.com e faz login com a tua conta Google (a mesma do Google Ads)
2
No topo da página, clica no seletor de projetos (dropdown ao lado do logo do Google Cloud)
3
Clica em "Novo Projeto" (ou "New Project")
4
Preenche: Nome do projeto (sugestão: Google Ads API ou Ads Ratos). Organização e local pode deixar o padrão
5
Clica em "Criar" e aguarda alguns segundos
6
Depois de criado, seleciona o projeto no dropdown do topo pra garantir que tá ativo
💡 O projeto é tipo uma "pasta" no Google Cloud. Ele agrupa APIs, credenciais e permissões. Tu pode usar um projeto só pra Google Ads ou compartilhar com outras APIs.
3
Passo 3 de 7

Ativar a Google Ads API e criar credenciais OAuth

Agora tu vai ativar a API do Google Ads no teu projeto e criar as credenciais OAuth. Parece complicado, mas é só seguir os cliques.

Parte A: Ativar a API

Ativando a API
1
No Google Cloud Console, vai no menu lateral: APIs e Serviços > Biblioteca (ou busca "Library" na barra de pesquisa)
2
Pesquisa "Google Ads API"
3
Clica no resultado e depois em "Ativar" (ou "Enable")

Parte B: Tela de Consentimento OAuth

Configurando o consentimento
1
Vai em APIs e Serviços > Tela de consentimento OAuth (ou "OAuth consent screen")
2
Seleciona "Externo" e clica em "Criar"
3
Preenche o nome do app (tipo Ads Ratos) e o e-mail de suporte (teu email). Os outros campos pode pular
4
Na tela de escopos, clica em "Adicionar ou remover escopos", busca "Google Ads API" (escopo: https://www.googleapis.com/auth/adwords), marca e confirma. Clica em "Salvar e continuar"
5
Na tela de usuários de teste, clica em "Add Users", digita o teu email (o mesmo do Google Ads), e salva
6
Confere o resumo e clica em "Voltar ao painel"

Parte C: Criar Client ID OAuth

Gerando as credenciais
1
Vai em APIs e Serviços > Credenciais (ou "Credentials")
2
Clica em "+ Criar Credenciais" > "ID do cliente OAuth" (ou "OAuth client ID")
3
Tipo de aplicativo: "App para computador" (ou "Desktop app")
4
Nome: pode deixar o padrão ou colocar Ads Ratos
5
Clica em "Criar"
6
Copia o Client ID e o Client Secret que aparecem na tela. Guarda esses dois valores!
O que tu conseguiu nesse passo
Credenciais
GOOGLE_ADS_CLIENT_ID="teu-client-id.apps.googleusercontent.com"
GOOGLE_ADS_CLIENT_SECRET="teu-client-secret"
4
Passo 4 de 7

Obter Developer Token

O Developer Token é a chave que identifica que tu tem permissão pra usar a API. Ele fica dentro do Google Ads, não no Google Cloud.

Pegando o token
1
Abre o Google Ads (ads.google.com) e entra na tua conta MCC
2
Vai em Ferramentas e Configurações (ícone de chave no menu superior) > procura por "Central de API" (ou "API Center")
3
Se for a primeira vez, vai pedir pra aceitar os termos. Aceita
4
O Developer Token aparece na tela. Copia ele
⚠️ O token começa com acesso de Teste (Test Account). Pra usar com contas reais, tu precisa pedir Basic Access (tem um formulário no mesmo lugar). A aprovação leva de 3 a 7 dias úteis.

Como pedir Basic Access

Passo a passo
1
Na mesma tela da Central de API, clica em "Aplicar para Basic Access"
2
Preenche o formulário. O campo mais importante é o "Use Case Description"
3
Em "API Token Contact Email", coloca teu email
4
Em "Direct or Third Party Tool", seleciona "Direct" (acesso direto, sem intermediário)
5
Envia e aguarda. A aprovação leva de 3 a 7 dias úteis

O Google rejeita descrições vagas. Aqui embaixo tem o texto pronto pra tu copiar e colar no campo "Use Case Description":

Use Case Description (cola no formulário)
We use the Google Ads API to manage advertising campaigns for our own business accounts. Our internal tool connects via the API to read campaign performance data (impressions, clicks, conversions, cost), create and update campaigns, ad groups, keywords, and responsive search ads, manage negative keyword lists, and generate performance reports. All operations are performed on accounts we own or manage directly through our MCC. We do not provide API access to third parties. The tool is used by our internal marketing team for day-to-day campaign management and optimization.

O formulário tem mais perguntas. Aqui vai o que responder em cada uma:

Todas as respostas do formulário
6
Describe your business model...: cola o texto pronto acima (o que já tá no bloco de copiar)
7
Design documentation: faz upload do PDF pronto que a gente preparou pra ti. Baixa aqui o PDF
8
Who will have access: marca "Internal users - employees only"
9
Tool developed by someone else?: marca "No"
10
App Conversion Tracking and Remarketing API?: marca "No"
11
Campaign types supported: escreve "Search, Performance Max"
12
Google Ads capabilities: marca Campaign Creation, Campaign Management, Reporting e Keyword Planning Services
Outros campos (se aparecerem)
→
Describe how you will comply... (compliance): "We only access accounts we own or manage. All API credentials are stored securely in environment variables, never shared or exposed publicly."
→
OAuth verification: se perguntar, marque que o app é de uso interno (não precisa de verificação pública)
💡 Enquanto espera a aprovação do Basic Access, tu já pode usar o token de Teste pra desenvolver e testar. Ele funciona igual, só não acessa contas reais com anúncios rodando.
O que tu conseguiu nesse passo
Credenciais
GOOGLE_ADS_DEVELOPER_TOKEN="teu-developer-token"
5
Passo 5 de 7

Pegar o Login Customer ID

Último dado que tu precisa copiar do Google. É o ID da tua conta MCC (aquele número de 10 dígitos que aparece no canto superior do Google Ads quando tu tá logado na MCC).

Copiando o ID
1
No Google Ads, entra na tua conta MCC
2
O Customer ID aparece no canto superior da tela, no formato XXX-XXX-XXXX
3
Copia os 10 dígitos sem hífens (ex: se aparece 123-456-7890, copia 1234567890)
O que tu conseguiu nesse passo
Credenciais
GOOGLE_ADS_LOGIN_CUSTOMER_ID="1234567890"
✅ Pronto! Agora tu tem os 4 dados que precisa. A parte chata acabou. Agora é só voltar pro VS Code e deixar o Claude fazer o resto.
6
Passo 6 de 7

Mandar pro Claude configurar

Agora volta pro VS Code com a pasta da skill aberta. Manda isso pro Claude:

Tu: configura a skill de google ads pra mim. meu client id é [COLA AQUI], client secret é [COLA AQUI], developer token é [COLA AQUI] e meu MCC é [COLA AQUI]

O Claude vai:

O que o Claude faz automaticamente
1
Criar o arquivo .env com todas as credenciais no lugar certo
2
Instalar as dependências Python (google-ads, google-auth-oauthlib)
3
Rodar o setup.py oauth pra gerar o refresh token (vai abrir teu browser, tu autoriza com tua conta Google, e ele salva tudo sozinho)
4
Testar a conexão com setup.py test
5
Mostrar as contas acessíveis
💡 Tu não precisa abrir terminal, não precisa editar arquivo nenhum manualmente. O Claude faz tudo. Se algo der erro, ele te avisa e tenta resolver.
7
Passo 7 de 7

Cadastrar tuas contas e testar

Depois que a conexão funcionar, o Claude vai te perguntar qual é a tua principal conta Google Ads. Responde normalmente:

Tu: minha conta principal é a Loja do João, customer id 9876543210

O Claude cadastra no contas.yaml e a partir daqui tu pode pedir qualquer coisa:

Tu: me mostra as campanhas da Loja do João
Tu: quero os insights dos últimos 30 dias
Tu: cria uma campanha de search chamada Promoção Verão com orçamento de R$50/dia
✅ Pronto! A skill tá configurada. Agora é só conversar com o Claude e ele executa tudo no Google Ads pra ti.