Configurar Google Ads API — Ratos de IA
🐀
Ratos de IA · Ads Ratos
Configurar Google Ads API
Progresso
0 de 7
📌 Atualizado em 21/10/2026. Em setembro o Google aposentou o developer token e tirou o pedido de acesso da Central de API do Google Ads. Agora o acesso é pedido dentro do Google Cloud, e a conta MCC deixou de ser obrigatória. Se a aula em vídeo mostra outra coisa, vale este passo a passo.

Tudo que tu precisa pra conectar a skill de Google Ads no Claude Code. Tu vai criar um projeto no Google Cloud, pedir o acesso à API e mandar duas chaves pro Claude. O resto ele faz. Leva uns 15 a 20 minutos.

Antes de começar
✅ Já tinha configurado antes de setembro? Não precisa refazer nada. O Google passou o teu acesso pro projeto do Google Cloud sozinho. Só atualiza a skill: baixa o zip novo na plataforma e manda pro Claude "checa a atualização da skill google-ads-ratos e aplica".
1
Passo 1 de 7

Criar um projeto no Google Cloud

O projeto é onde ficam as chaves que a skill usa. Desde setembro é também ele que recebe a permissão de usar a API do Google Ads.

Criando o projeto
1
Abre console.cloud.google.com/projectcreate com a mesma conta Google que acessa o Google Ads
2
Em Nome do projeto, escreve Ads Ratos. Organização e local podem ficar no padrão
3
Clica em Criar e espera uns segundos
4
No seletor de projetos, no topo da página, confere se o Ads Ratos está selecionado. Todos os passos seguintes precisam ser feitos com ele selecionado
💡 Já tem um projeto do Google Cloud de outra skill (GA4, por exemplo)? Pode usar o mesmo. Só não cria dois projetos pra mesma coisa, porque o acesso fica preso ao projeto que pediu.
2
Passo 2 de 7

Ativar a Google Ads API

Um clique. Ao ativar, o teu projeto ganha o nível de acesso Teste. No passo 5 tu pede o nível que enxerga as tuas contas de verdade.

Ativando
1
Abre este link direto pra ativar a Google Ads API
2
Confere se o projeto selecionado é o Ads Ratos e clica em Ativar (ou Enable)
💡 Se o link não abrir, o caminho é: menu lateral > APIs e serviços > Biblioteca > busca "Google Ads API" > Ativar.
3
Passo 3 de 7

Configurar a tela de permissão

É a tela que aparece quando a skill pede pra acessar a tua conta. O Google chama essa área de Google Auth Platform.

Parte A: dados do app

Primeira configuração
1
Abre console.cloud.google.com/auth/overview e clica em Começar (ou Get started)
2
Informações do app: nome Ads Ratos e o teu e-mail como e-mail de suporte. Clica em Próxima
3
Público-alvo: marca Externo. Próxima
4
Informações de contato: o teu e-mail de novo. Próxima
5
Aceita a política de dados do Google e clica em Criar

Parte B: permissão do Google Ads

Adicionando o escopo
1
No menu da esquerda, clica em Acesso a dados (ou Data access)
2
Clica em Adicionar ou remover escopos, busca Google Ads API e marca o escopo .../auth/adwords
3
Clica em Atualizar e depois em Salvar, no fim da página

Parte C: publicar o app

Tirando do modo teste
1
No menu da esquerda, clica em Público-alvo (ou Audience)
2
Em Status de publicação, clica em Publicar app e confirma
⚠️ Não pula a Parte C. Com o app em modo Teste, o Google faz a autorização vencer em 7 dias, e a skill para de funcionar uma semana depois sem aviso. Publicar não deixa o app aberto pra ninguém: as chaves continuam só contigo.
4
Passo 4 de 7

Criar as chaves (Client ID e Client Secret)

São as duas chaves que tu vai mandar pro Claude.

Gerando as chaves
1
Ainda na Google Auth Platform, clica em Clientes (ou Clients) no menu da esquerda
2
Clica em + Criar cliente
3
Em Tipo de aplicativo, escolhe App para computador (ou Desktop app)
4
Nome: Ads Ratos. Clica em Criar
5
Copia o ID do cliente e a Chave secreta do cliente e guarda num lugar seguro. Se tiver o botão Baixar JSON, baixa também
⚠️ Copia a chave secreta antes de fechar a janela. O Google só mostra ela inteira nessa hora. Se perder, dá pra criar outra chave secreta no mesmo cliente, sem refazer nada.
O que tu conseguiu nesse passo
Chaves
GOOGLE_ADS_CLIENT_ID="teu-client-id.apps.googleusercontent.com"
GOOGLE_ADS_CLIENT_SECRET="tua-chave-secreta"
5
Passo 5 de 7

Pedir o acesso Explorer

Este passo substituiu o antigo developer token. O nível Teste, que veio no passo 2, só enxerga contas de teste. O Explorer enxerga as tuas contas de verdade, e o Google costuma aprovar na hora, sem análise manual.

Pedindo o Explorer
1
Abre a página Google Ads API Overview, com o projeto Ads Ratos selecionado
2
Confere que o nível atual (Access level) está em Test
3
Abre a seção Upgrade access level e confere que o próximo nível (Next access level) é Explorer
4
Clica em Apply for access. Se aparecer um formulário, preenche com os dados da tua empresa. O texto pronto logo abaixo serve pra qualquer campo que peça a descrição do uso
5
Recarrega a página depois de uns minutos. Quando o nível mostrar Explorer, segue pro passo 6
Descrição do uso (se o formulário pedir)
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. 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.
Os níveis de acesso
Teste Só contas de teste. Vem sozinho ao ativar a API
Explorer Tuas contas de verdade, até 2.880 operações por dia. Ler, criar, editar e pausar campanhas funciona. Não inclui o Keyword Planner
Basic Até 15.000 operações por dia, com Keyword Planner. Exige a verificação de marca (ver "Precisa de mais?" no fim da página)
💡 2.880 operações por dia sobra pra quem gerencia as próprias contas. Uma consulta de campanhas, por exemplo, gasta uma operação.
6
Passo 6 de 7

Mandar pro Claude configurar

Volta pro VS Code e manda isso pro Claude:

Tu: configura a skill google-ads-ratos pra mim. meu client id é [COLA AQUI] e o client secret é [COLA AQUI]

Se tu gerencia as contas por uma conta de gerenciamento (MCC), acrescenta no fim: "e meu MCC é [ID DA MCC]". Se não sabe o que é MCC, não precisa.

O que o Claude faz
1
Instala o que falta no Python e cria o arquivo .env com as tuas chaves
2
Abre o navegador pra tu autorizar com a tua conta Google
3
Testa a conexão e mostra as contas que achou
⚠️ Na autorização vai aparecer "O Google não verificou este app". É esperado: o app é o teu, criado no passo 3. Clica em Avançado e depois em Acessar Ads Ratos (não seguro). Na tela seguinte, marca a permissão do Google Ads e clica em Continuar.
7
Passo 7 de 7

Cadastrar tuas contas e testar

Depois que a conexão funcionar, o Claude pergunta qual é a tua conta principal. Responde normalmente:

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

O Claude grava no contas.yaml, e a partir daí tu pede o que quiser:

Tu: me mostra as campanhas da Loja do João
Tu: quero os resultados dos últimos 30 dias
✅ Pronto! A skill está configurada. Se algo der erro, olha a seção "Deu erro?" logo abaixo.
Deu erro? Os casos mais comuns
invalid_grant, uma semana depois de funcionar

O app ficou em modo Teste e a autorização venceu. Faz a Parte C do passo 3 (Publicar app) e manda pro Claude: "gera de novo o refresh token do google ads".

DEVELOPER_TOKEN_NOT_APPROVED

O nome é antigo, mas o erro quer dizer que o nível de acesso do projeto não cobre o pedido. Se o projeto ainda está em Teste, faz o passo 5. Se já está em Explorer e o erro veio numa pesquisa de palavras-chave, é o Keyword Planner, que exige o nível Basic.

Google Ads API has not been used in project

A API não foi ativada nesse projeto. Faz o passo 2 com o projeto certo selecionado.

USER_PERMISSION_DENIED

A conta Google que tu autorizou não tem acesso a essa conta de anúncios. Confere no Google Ads, em Administrador > Acesso e segurança. Se a conta fica dentro de uma MCC, passa o ID da MCC pro Claude.

access_denied ou "acesso bloqueado" na hora de autorizar

O app ainda está em modo Teste e o teu e-mail não está na lista de usuários de teste. Publica o app (passo 3, Parte C) e tenta de novo.

O Claude pede um developer token

A skill está numa versão antiga. Baixa o zip novo na plataforma e manda: "checa a atualização da skill google-ads-ratos e aplica".

Precisa de mais? Keyword Planner e o nível Basic

O Explorer cobre o uso do dia a dia. O Basic só faz falta se tu quer a pesquisa de palavras-chave (Keyword Planner) pela skill, ou se passa de 2.880 operações por dia. Pra pedir, o Google exige a verificação de marca do projeto, e ela pede um site teu no ar.

Do Explorer pro Basic
1
Tenha um site com página inicial pública e uma política de privacidade no mesmo domínio
2
Verifica esse domínio no Google Search Console com a mesma conta Google do projeto
3
Na Google Auth Platform, em Branding: preenche logo, página inicial, link da política de privacidade e o domínio em Domínios autorizados
4
Em Central de verificação (ou Verification Center), pede a verificação da marca. Costuma sair em minutos. Se cair em revisão manual, leva de 2 a 3 dias úteis
5
Volta na Google Ads API Overview, abre Upgrade access level e clica em Apply for access. O texto de descrição do passo 5 serve aqui também. Se pedirem um documento do projeto, baixa aqui o PDF pronto

Enquanto o Basic não sai, a skill segue funcionando no Explorer. Só a pesquisa de palavras-chave fica de fora.