Ferramentas

Como conectar Claude Code ao Meta Ads com o CLI oficial em 2026

Fluxo seguro para usar o CLI oficial do Meta Ads com Claude Code: permissões, token, consultas somente leitura, proteção de credenciais e validação.

4 min de leitura

O Claude Code pode consultar dados do Meta Ads chamando o CLI oficial da Meta no terminal. A conexão não é um botão mágico: ela depende de um app autorizado, um token com as permissões corretas e regras claras para impedir que uma instrução errada altere campanhas ou orçamento.

A configuração mais segura começa somente com leitura. Depois que conta, período, métricas e saída forem validados, você decide se libera operações de escrita.

Como a integração funciona

  1. O CLI traduz comandos de terminal em requisições à Marketing API.
  2. O token determina quais contas e operações estão permitidas.
  3. O Claude Code executa o comando, lê a saída estruturada e ajuda a analisar.
  4. Qualquer alteração continua sujeita às permissões, políticas e revisão da Meta.

O anúncio do produto e a referência atual ficam no blog de desenvolvedores da Meta e na documentação do Ads CLI. Use essas páginas como fonte de instalação; existem pacotes comunitários com nomes parecidos.

Pré-requisitos

  • portfólio empresarial e conta de anúncios aos quais você tenha acesso legítimo;
  • app do tipo adequado com Marketing API;
  • permissão ads_read para relatórios e ads_management apenas quando escrita for necessária;
  • CLI oficial instalado conforme a documentação corrente;
  • Claude Code rodando em uma pasta confiável, sem expor o token em arquivos versionados.

1. Gere uma credencial com o menor acesso necessário

Crie ou selecione o app e o usuário de sistema no ambiente empresarial da Meta. Vincule somente os ativos necessários. Para começar, prefira leitura. Tokens, duração e requisitos variam conforme o tipo de app, o nível de acesso e a revisão de permissões; não trate qualquer token como “permanente”.

Nunca publique o token no artigo, prompt, repositório, captura de tela ou histórico compartilhado. Prefira um gerenciador de segredos ou arquivo local com permissão restrita. Evite adicionar o valor diretamente ao arquivo de configuração do shell quando outras pessoas ou processos usam a mesma máquina.

2. Instale e confirme o CLI oficial

Siga o comando de instalação exibido na documentação da Meta e, em seguida, valide a própria ajuda do binário:

meta --help
meta ads --help
meta auth status

Os comandos são a fonte da verdade para a versão instalada. Se um tutorial mostrar meta-ads como binário, compare com a ajuda oficial: ferramentas independentes podem usar esse nome.

3. Faça o primeiro teste em modo leitura

Comece listando as contas acessíveis e depois consulte a ajuda do recurso de insights:

meta ads adaccount list
meta ads insights get --help

Monte a primeira consulta com uma única conta, período curto e poucas métricas. Não cole um ID real em documentação pública. Salve a saída em JSON quando ela será analisada por script ou pelo Claude.

4. Dê ao Claude uma tarefa verificável

Um bom pedido identifica conta, período, nível e saída esperada:

Use apenas comandos de leitura. Consulte a conta definida na variável segura, compare os últimos sete dias completos com os sete anteriores e devolva gasto, impressões, cliques e conversões por campanha. Não altere nada e mostre o comando antes de executar.

Peça que a análise preserve valores ausentes, informe a moeda e diferencie zero de dado não retornado. Antes de tomar decisão, confira uma amostra no Gerenciador de Anúncios.

5. Coloque barreiras antes de liberar escrita

  • usar uma conta de teste ou campanha pausada;
  • exigir confirmação humana para criar, editar, ativar ou pausar;
  • definir teto de orçamento fora do prompt;
  • registrar comando, operador, horário e resposta da API;
  • nunca executar em lote antes de validar um item;
  • manter plano de reversão para cada alteração.

A IA pode sugerir uma ação, mas não conhece sozinha margem, estoque, contrato ou compromisso com o cliente. A aprovação continua sendo decisão operacional.

Problemas comuns

Comando não encontrado

Confirme a instalação oficial, o ambiente usado e o caminho do executável. Rode a ajuda diretamente no mesmo terminal aberto pelo Claude Code.

Token inválido ou sem permissão

Verifique expiração, ativos atribuídos e escopos. Não amplie permissões antes de identificar a operação que falhou.

Conta não aparece

O usuário ou usuário de sistema precisa ter acesso à conta dentro do portfólio empresarial. Ter acesso a uma Página não garante acesso à conta de anúncios.

Números diferentes do painel

Confira fuso, moeda, janela de atribuição, período ainda incompleto, nível do relatório e definição de cada métrica.

Como verificamos e quais são os limites

Revisão baseada no anúncio oficial do Ads CLI, na documentação técnica da Meta e na Marketing API. Sintaxe, versões e permissões mudam; confirme --help e a documentação antes de executar.

Perguntas frequentes

Preciso liberar escrita?

Não. Relatórios e diagnósticos funcionam com leitura. Escrita só deve ser liberada quando houver caso real, revisão e barreiras fora do prompt.

Posso colocar o token no prompt?

Não. O prompt pode aparecer em histórico, log ou ferramenta. Injete a credencial no processo por meio seguro e nunca peça ao modelo para reproduzi-la.