Como Conectar Claude Code à Meta Ads em 5 Minutos (Sem OAuth, Sem Complicação)

Cara, vou ser direto: depois que a Meta lançou o CLI oficial em 29/04/2026, conectar Claude Code à sua conta de anúncios virou trivial. Tipo "5 minutos do começo ao fim" trivial. E não exige OAuth nem nada complicado.

Esse tutorial é pra você que sabe o que é Claude Code, sabe o que é Meta Ads, mas nunca conectou os dois. No final você vai ter o Claude Code conversando com sua conta real, puxando insight, criando relatório, ajustando campanha — tudo via terminal.

Vou contar passo a passo do jeito que fizemos na agência aqui (testamos hoje cedo, 1º de maio, em 27 contas reais). Sem teoria, só prática.

Por que CLI e não MCP (na maioria dos casos)

Primeiro, contexto rápido. A Meta lançou DUAS coisas em 29/04/2026:

• MCP server oficial em https://mcp.facebook.com/ads — usa OAuth, roda dentro do Claude Desktop ou ChatGPT, ocupa 134k tokens só pra carregar tools
• CLI oficial meta-ads — comando de terminal, autenticação via ACCESS_TOKEN simples, funciona em qualquer ambiente

Pra usar com Claude Code especificamente, o CLI é melhor por 3 motivos:

1. MCP remoto está bloqueado no Remote Control do Claude Code — você precisa de MCP local. CLI não tem essa restrição
2. Token simples vs OAuth — CLI usa só ACCESS_TOKEN. MCP exige browser pra fazer OAuth, o que não funciona em terminal puro
3. Não consome contexto à toa — MCP carrega 134k tokens só pra estar disponível. CLI é chamado on-demand, gasta zero token pra estar instalado

Se você usa Claude Code no terminal (que é o que recomendo pra trabalho com infra/dados), CLI é o caminho. Se você usa Claude Desktop com chat visual, aí MCP faz sentido.

Pré-requisitos: o que você precisa antes

Antes de começar, garanta que você tem:

• Python 3.12 ou superior — se você tem 3.11 ou anterior, instala o 3.12 via pyenv ou usa uv pra isolar (vou mostrar como)
• Conta de anúncios Meta ativa — pode ser pessoal, BM, conta de cliente, qualquer uma onde você tem permissão de admin
• Acesso a developers.facebook.com — pra gerar o token. Se nunca entrou lá, é o portal de desenvolvedores da Meta, login com sua conta normal Facebook
• Claude Code instalado — se ainda não tem, baixa via npm install -g @anthropic-ai/claude-code

Se faltar algo dessa lista, resolve antes. Se está tudo OK, vamos pro passo 1.

Passo 1: Gerar o ACCESS_TOKEN da Marketing API

Esse é o passo mais demorado da primeira vez (uns 5-10 minutos). Mas você faz uma vez e o token vale pra sempre.

1.1 — Acessar developers.facebook.com

Abre developers.facebook.com e faz login. Se nunca entrou, vai pedir pra criar conta de desenvolvedor — aceita os termos, pronto.

1.2 — Criar um app

Clica em My Apps → Create App. Tipo: Business. Nome: qualquer coisa (ex: "Meu CLI Meta Ads"). Cria o app.

1.3 — Adicionar Marketing API ao app

Dentro do app, lateral esquerda: Add Product → Marketing API. Setup. Pronto, agora seu app tem Marketing API habilitada.

1.4 — Gerar System User Token

Vai pro Business Manager → Configurações de Negócio → System Users (Usuários do Sistema). Cria um System User com role de Admin. Atribui o app que você criou. Depois clica em Generate New Token e seleciona as permissões:

• ads_read — leitura
• ads_management — escrita (criar/editar/pausar)
• business_management — opcional, se quer mexer em BM

O token vai aparecer uma vez. COPIA AGORA — depois você não consegue ver de novo, só gerar outro. Salva num gerenciador de senhas tipo 1Password ou num arquivo .env seguro.

Passo 2: Instalar o CLI meta-ads

Aqui você tem 2 opções. Vou recomendar a 2 porque é mais limpa.

Opção A — pip clássico (mais simples, polui ambiente global)

pip install meta-ads

Funciona, mas instala no Python global. Se já tem outras libs instaladas, pode dar conflito.

Opção B — uv (recomendado, isolado e rápido)

uv é o gerenciador de pacotes Python da Astral, mais rápido que pip e não polui o ambiente global. Se não tem, instala primeiro:

curl -LsSf https://astral.sh/uv/install.sh | sh

Depois instala o CLI isolado:

uv tool install meta-ads --python 3.12

O uv tool cria um venv isolado pra cada CLI, então o meta-ads não conflita com nada. Recomendo essa via.

Verificar instalação

meta --version
# Output esperado:
# meta-ads, version 1.0.1

Se aparecer a versão, instalou direitinho. Se der "command not found", precisa adicionar o path do uv ao PATH (geralmente ~/.local/bin).

Passo 3: Autenticar com export ACCESS_TOKEN

Lembra do token que você gerou no passo 1? Agora exporta ele como variável de ambiente:

export ACCESS_TOKEN=EAA...seu_token_completo_aqui

Isso vale pra sessão atual do terminal. Se quer permanente, adiciona essa linha ao seu ~/.zshrc ou ~/.bashrc:

echo 'export ACCESS_TOKEN=EAA...' >> ~/.zshrc
source ~/.zshrc

Cuidado: NUNCA comita esse token em repositório git. Adiciona .env ao .gitignore e usa lib tipo python-dotenv em scripts.

Passo 4: Primeiro comando — listar contas

Hora da verdade. Roda:

meta -o json ads adaccount list | head -50

Se tudo deu certo, você vai ver as suas contas de anúncios em formato JSON. Tipo:

[
  {
    "id": "act_495805727467051",
    "name": "WeLiKe — Cliente Café",
    "currency": "BRL",
    "timezone": "America/Sao_Paulo",
    "account_status": 1
  },
  ...
]

O parâmetro -o json pede output em JSON (mais fácil de parsear em script). Sem ele, sai como tabela legível pra olho humano:

meta ads adaccount list

# Output em tabela:
# ID                       Name                      Currency  Status
# act_495805727467051      WeLiKe — Cliente Café    BRL       Active
# act_123456789012345      Outra Conta              BRL       Active
# ...

Pra cada conta, o ID começa com act_. Anota o ID das que você quer trabalhar — vai usar nos próximos comandos.

Passo 5: Puxar insights de uma conta

Esse é o comando que mais vai te servir no dia a dia. Pra puxar performance dos últimos 7 dias de uma conta:

meta ads insights get   --account-id act_495805727467051   --date-preset last_7d   --fields spend,impressions,clicks,ctr,cpc,reach,actions   -o table

Output (real, da nossa conta WeLiKe hoje):

Outros date-preset úteis: today, yesterday, last_3d, last_14d, last_30d, this_month, last_month, maximum (vida toda da conta).

Se quer dados de uma campanha específica (não a conta inteira), adiciona --level campaign:

meta ads insights get   --account-id act_495805727467051   --date-preset last_7d   --level campaign   --fields campaign_name,spend,clicks,ctr

Conectando ao Claude Code: ele chama o CLI por você

Aqui é onde o jogo vira. Em vez de você lembrar todos esses comandos, você simplesmente conversa com o Claude Code.

Abre o Claude Code no terminal:

cd ~/seu_projeto
claude

E pede em linguagem natural:

"Roda meta ads adaccount list e me mostra as contas ativas. Depois pra cada uma, puxa insights dos últimos 7 dias e me dá um resumo com spend, leads e CPL médio."

O Claude Code vai:

1. Rodar o comando do CLI no terminal (com sua autorização, claro)
2. Receber o output
3. Iterar nas contas
4. Calcular CPL pra cada
5. Te entregar um relatório formatado

Tudo isso em uns 30 segundos, em vez dos 30 minutos que você gastaria no Ads Manager.

Exemplo real de prompt que uso

Esse é literalmente o prompt que rodo toda manhã na agência:

"Pra cada uma das 27 contas ativas (lista em /tmp/contas_ativas.txt),
roda 'meta ads insights get --account-id ID --date-preset yesterday
--fields spend,impressions,clicks,ctr,actions' e gera um relatório com:
1. Top 5 contas que mais gastaram
2. Top 5 contas com pior CTR (alerta)
3. Contas sem leads em 24h (alerta urgente)
4. Total spend agregado
Manda esse relatório formatado pra mim em markdown."

Esse prompt economiza umas 2 horas por dia. E é commodity agora — qualquer agência pode fazer.

Troubleshooting: os 4 erros mais comuns

Erro 1 — "command not found: meta"

Você instalou via uv tool mas o PATH não tá certo. Roda:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
meta --version

Erro 2 — "401 Unauthorized" ou "Invalid OAuth access token"

O token tá errado, expirou (raro com System User), ou não tem permissão. Verifica:

• Token tem prefixo EAA...? Se não, copiou errado
• Tem permissão ads_read e ads_management?
• O System User tem role de admin no BM?
• Tenta gerar um token novo no Business Manager e testa

Erro 3 — "Python 3.12 or higher required"

Você instalou no Python errado. Resolve:

uv tool uninstall meta-ads
uv tool install meta-ads --python 3.12

Erro 4 — "Rate limit exceeded"

A Marketing API tem limite de requests por hora. Se você tá fazendo muito request (tipo loop em 100 contas chamando insights 1 por 1), bate o teto. Soluções:

• Espera 1 hora e tenta de novo (limite resetá)
• Usa --batch quando o comando suportar
• Aumenta intervalo entre requests no script (sleep 2s entre cada)
• Pra volume real, usa a documentação oficial de best practices que tem dicas avançadas

Próximos passos: o que fazer agora

Você acabou de conectar Claude Code à sua conta de anúncios. Próximos passos naturais:

1. Documenta os IDs das suas contas num arquivo tipo contas.txt pra reutilizar
2. Cria um prompt template de relatório diário (igual o exemplo acima)
3. Automatiza com cron — roda o relatório toda manhã às 8h e dispara via WhatsApp (vou mostrar isso em outro artigo do blog sobre relatório diário Meta Ads no WhatsApp)
4. Estuda os 29 tools do MCP — mesmo que use CLI, conhecer os tools te ajuda a saber o que pedir
5. Testa criação de campanha via Claude Code — pede pra ele criar uma campanha de teste em status PAUSED. Vai criar mesmo

Conclusão: 5 minutos pra mudar como você trabalha

Cara, sério, esse tutorial é um divisor de águas. Se você seguiu até aqui e instalou tudo, você tem na mão a mesma stack que a maioria das agências do Brasil ainda não tem. Janela de vantagem aberta.

Próximas semanas vou continuar publicando tutoriais relacionados — comparativo entre as opções de MCP/CLI, workflow completo de relatório diário, casos de uso avançados. Salva o blog nos favoritos.

E qualquer dúvida durante a instalação, me chama no WhatsApp. Resposta rápida.

Perguntas Frequentes (FAQ)

Felipe Zanoni

Fundador da Agência Café Online. Especialista em agentes de IA, automação empresarial e marketing digital. Ver perfil completo