PRÉ-REQUISITOS COMPLETOS

Antes de tocar em qualquer coisa, confirme cada um dos itens abaixo. Faltando qualquer um, pare e resolva primeiro.

2.1 Conta e Business Manager

• Conta admin na Business Manager (BM) com permissões totais.
• BM com Verificação da Empresa concluída, status "Verificado" no painel da BM. Sem isso, a Meta limita permissões avançadas e pode bloquear geração de token de System User.
• Conta de anúncios ativa, com método de pagamento válido, vinculada à BM.

2.2 Conta de desenvolvedor

• Conta de desenvolvedor Meta criada em developers.facebook.com.
• Email de contato funcional (a Meta envia notificações críticas pra esse email).
• Verificação por SMS habilitada na conta (a Meta exige SMS em ações sensíveis como gerar token).

2.3 Stack técnica

• Python 3.10+ instalado.
• Claude Code CLI instalado e funcionando.
• Acesso ao terminal com permissão de instalar pacotes Python.
• Editor de texto para configurar arquivo .env.
• Gerenciador de senhas (1Password, Bitwarden) para guardar token e App Secret.

2.4 Domínio e Política de Privacidade

• Domínio próprio (ou subdomínio) para hospedar a Política de Privacidade.
• Página de Política de Privacidade publicada e acessível via HTTPS.
• Pode ser uma página estática no GitHub Pages, Vercel, Cloudflare Pages, ou qualquer host estático.
• Sem isso o App não sai do modo desenvolvimento.

2.5 Checklist rápido

• Sou admin de uma BM verificada.
• Conta de anúncios ativa vinculada à BM.
• Conta dev Meta criada com SMS habilitado.
• Python 3.10+ no terminal.
• Claude Code instalado.
• Domínio com Política de Privacidade publicada.

FASE 1 — CRIAR APP TIPO BUSINESS

O App é a ponte entre o servidor MCP (que você vai rodar) e a API da Meta. Tem que ser do tipo certo, com o produto certo habilitado.

3.1 Por que App tipo Business e não Use-Case

A Meta oferece dois tipos de App:

Importante: se você abrir o use-case APP_INSTALL_ADS, a própria Meta avisa: "Não inclui acesso à API de Marketing." Nenhum dos use-cases atuais oferece Marketing API. Se criar App use-case por engano, descarta e cria de novo do tipo Business.

3.2 Passo a passo de criação

1. Acesse developers.facebook.com, faça login.
2. Vá em Meus Apps no menu superior.
3. Clique em Criar App.
4. Na tela de seleção de tipo, escolha "Empresa" (em inglês, "Business").
5. Preencha:

- Nome do app: descritivo, ex: "Avalanche Tráfego MCP", "7D Secrets API", "Cliente X Ads Bot". - Email de contato: email do admin responsável. - Business Manager: selecione a BM correta na qual o App será vinculado. Esse passo é crítico, sem vincular à BM o App não consegue gerar token de System User depois.

1. Clique em Criar App.
2. A Meta pode pedir verificação por SMS nesse momento.
3. App criado em modo Desenvolvimento.

3.3 Adicionar produto API de Marketing

App criado, agora habilita o produto:

1. No painel do App, menu lateral esquerdo, clique em Adicionar produto.
2. Localize API de Marketing (Marketing API).
3. Clique em Configurar.
4. O produto aparece no menu lateral como API de Marketing.

Em alguns casos, se o App já foi criado tipo Business e vinculado à BM, a API de Marketing aparece habilitada automaticamente. Confirme no menu lateral.

3.4 Configurações básicas obrigatórias

Vá em Configurações do App > Básico e preencha:

• URL da Política de Privacidade: obrigatório. Cole a URL completa, ex: https://denderson.com/privacy. Sem isso, o App não passa para o modo Ao Vivo.
• Email de contato: email do admin (já preenchido na criação).
• Categoria: escolha Negócio e Páginas.
• Ícone do App: 1024x1024px. Opcional mas recomendado.
• Domínios do App: adicione o domínio onde a Política de Privacidade está hospedada.
• URL dos Termos de Serviço: opcional para Marketing API, mas recomendado para passar review depois.

Salva alterações.

3.5 Publicar em modo Ao Vivo

Em modo Desenvolvimento, só admins do App conseguem usar o token. Para System Users funcionarem sem restrição, o App tem que estar em modo Ao Vivo:

1. No topo do painel do App, localize Modo do aplicativo: desenvolvimento.
2. Clique no toggle para Ao Vivo.
3. A Meta verifica:

- Política de Privacidade preenchida e válida. - Categoria definida. - App vinculado a uma BM verificada.

1. Confirme.
2. App agora está Ao Vivo.

Em modo Ao Vivo, o App pode operar com qualquer System User da BM, sem restrição de admins.

3.6 Anotar credenciais do App

No painel do App, em Configurações > Básico, anote:

• App ID (numérico, visível no topo).
• App Secret (clique em "Mostrar", a Meta pede senha do Facebook para revelar).

Salve em gerenciador de senhas. Você vai usar no .env na Fase 4.

FASE 2 — CRIAR E CONFIGURAR SYSTEM USER

System User é o usuário técnico que vai assinar todas as chamadas de API. Ele não é uma pessoa, é uma identidade da BM.

4.1 Diferença entre User Token e System User Token

Documentação Meta confirma: System Users são "servidor ou elementos de software" que executam chamadas de API para ativos gerenciados pelo Business Manager.

A Meta também distingue dois níveis:

• Admin System User: permissões administrativas completas. Pode gerenciar a BM inteira.
• System User regular: permissões limitadas conforme configurado. Mais restrito, mais seguro.

Para Marketing API operacional, Admin System User é o caminho mais simples e dá controle total.

4.2 Criar o System User

1. Acesse business.facebook.com.
2. Vá em Configurações da Empresa (ícone de engrenagem).
3. No menu lateral, Usuários > Usuários do sistema.
4. Clique em Adicionar.
5. Preencha:

- Nome: um identificador claro, ex: "Avalanche Bot", "Claude MCP", ou um número de telefone do servidor. - Função: escolha Admin para controle total.

1. Confirme. System User criado.

4.3 Atribuir conta de anúncios ao System User

Sem essa atribuição, o token vai existir mas não vai conseguir mexer em nenhuma conta:

1. Na página do System User recém-criado, clique em Atribuir ativos (Add Assets).
2. Selecione Contas de anúncios (Ad Accounts).
3. Localize a conta de anúncios pelo nome ou ID (ex: act_123456789).
4. Marque a conta.
5. Em permissões, ative Controle total (Full Control).
6. Clique em Salvar alterações.

Repita para cada conta de anúncios que esse System User vai operar. Pode atribuir várias contas ao mesmo System User.

4.4 Atribuir App ao System User

Esse passo é o que mais gera erro depois (mensagem "Nenhuma permissão disponível" na geração de token):

1. Em Configurações da Empresa, no menu lateral, vá em Contas > Apps.
2. Selecione o App criado na Fase 1.
3. Clique em Atribuir pessoas.
4. Na lista, selecione o System User criado no passo 4.2.
5. Permissão: Controle total.
6. Confirme.

4.5 Atribuir Páginas (se for usar criativos com Page identity)

Se as campanhas vão rodar com Page como identidade do anúncio (caso normal de Facebook/Instagram Ads), atribua também:

1. Na página do System User, Atribuir ativos > Páginas.
2. Selecione a Page do cliente.
3. Permissão: Criar conteúdo (Create Content) no mínimo, ou Controle total.
4. Salvar.

4.6 Validação visual

Volte na página do System User e confirme nos cards:

• Apps atribuídos (deve aparecer o App).
• Contas de anúncios atribuídas (deve aparecer ao menos uma).
• Páginas atribuídas (se aplicável).

FASE 3 — GERAR TOKEN PERMANENTE

Token gerado uma vez, copiado uma vez, guardado em segurança. Se perder, gera de novo.

5.1 Fluxo de geração (4 etapas)

1. Em Configurações da Empresa > Usuários do sistema, selecione o System User criado.
2. Clique em Gerar token (Generate New Token).

5.2 Etapa 1 , Selecionar App

Aparece uma lista de Apps disponíveis. Só apps que foram atribuídos ao System User na Fase 2 aparecem aqui. Selecione o App da Fase 1.

Se o App não aparece: você esqueceu de atribuir o App ao System User. Volte na Fase 2, item 4.4.

5.3 Etapa 2 , Definir expiração

Duas opções:

• 60 dias: padrão recomendado pela Meta. Precisa renovar a cada 60 dias via fluxo de extend.
• Nunca: token permanente, sem expiração. Ideal para integração de servidor.

Para o método Avalanche, escolha Nunca. Token permanente é o caminho.

5.4 Etapa 3 , Atribuir permissões

Selecione exatamente estas três permissões (escopos):

Sem ads_management o token não cria nem edita nada (vira read-only). Sem ads_read o token não lê insights. Sem business_management o token não consegue ler estrutura da BM.

Adicione qualquer escopo extra apenas se for usar funcionalidade específica (pages_show_list, pages_manage_posts, instagram_basic, etc.).

5.5 Etapa 4 , Verificação SMS e cópia do token

1. Clique em Gerar token (Generate Token).
2. A Meta pode pedir verificação por SMS. Confirme o código.
3. O token aparece UMA ÚNICA VEZ na tela.
4. Copie imediatamente.
5. Cole em arquivo seguro (gerenciador de senhas) ou direto no .env do servidor.

Se você fechar a tela sem copiar, perdeu. Tem que gerar de novo.

5.6 Verificar token

Antes de seguir, valide que o token funciona com uma chamada simples:

curl -G "https://graph.facebook.com/v25.0/me" \
  -d "access_token=SEU_TOKEN_AQUI"

Resposta esperada: JSON com o ID do System User. Se vier erro 190 (token inválido), gere de novo.

curl -G "https://graph.facebook.com/v25.0/me/adaccounts" \
  -d "access_token=SEU_TOKEN_AQUI"

Resposta esperada: lista das contas de anúncios atribuídas. Se vier vazia, falta atribuir conta de anúncios ao System User (Fase 2, item 4.3).

FASE 4 — MONTAR O MCP SERVER

Aqui você instala (ou cria) o servidor MCP que vai expor as ferramentas Marketing API para o Claude Code consumir.

6.1 Duas estratégias possíveis

Estratégia A , Usar MCP server pronto (recomendado para começar)

Existe um projeto open source maduro: pipeboard-co/meta-ads-mcp no GitHub. Ele expõe 29 ferramentas cobrindo praticamente todos os endpoints da Marketing API. É o caminho mais rápido.

• Repositório: https://github.com/pipeboard-co/meta-ads-mcp
• Licença: Business Source License 1.1 (vira Apache 2.0 em jan/2029).
• 29 ferramentas (lista completa na seção 6.5).

Estratégia B , Criar seu próprio MCP server (recomendado para operação Avalanche)

Para controle total, customizar respostas, adicionar lógica de negócio (ex: integração com CRM Avalanche), você cria um MCP server próprio em Python. O playbook "Meta Marketing API · Integração com Claude via MCP" descreve uma versão de 14 ferramentas, mais enxuta e auditável.

Recomendação: comece com pipeboard, depois fork ou implementa o próprio se precisar de customização.

6.2 Stack do servidor

Independente da estratégia, a stack é:

• Python 3.10+
• Bibliotecas:

- mcp (Model Context Protocol) - httpx (cliente HTTP assíncrono) - pydantic (validação de schemas) - python-dotenv (carregar .env) - facebook-business (SDK oficial Meta, opcional)

• Estrutura mínima de arquivos:

~/meta-ads-mcp/
├── server.py            # MCP server principal
├── .env                 # Credenciais sensíveis (NUNCA commitar)
├── requirements.txt     # Dependências Python
└── README.md            # Instruções

6.3 Arquivo .env

O .env armazena todas as credenciais. Nunca commitar em repositório público. Adicione .env no .gitignore antes de qualquer commit.

# .env
META_ACCESS_TOKEN=EAAB...   # Token permanente do System User (Fase 3)
META_AD_ACCOUNT_ID=123456789012345  # ID da conta SEM o prefixo "act_"
META_APP_ID=123456789012345  # App ID (Fase 1, item 3.6)
META_APP_SECRET=abc123def456  # App Secret (Fase 1, item 3.6)
META_API_VERSION=v25.0  # Versão atual da Graph API

Notas importantes:

• META_AD_ACCOUNT_ID é o ID numérico sem o prefixo act_. O prefixo é adicionado pelo servidor automaticamente ao montar a URL.
• META_API_VERSION deve ser sempre uma versão ativa. Em abril/2026, v25.0 é estável. Confira em developers.facebook.com/docs/graph-api/changelog antes de usar versão mais nova.
• META_APP_SECRET é necessário para o fluxo de "extend token" e para appsecret_proof em chamadas seguras.

6.4 Arquivo requirements.txt

mcp>=0.4.0
httpx>=0.27.0
pydantic>=2.0
python-dotenv>=1.0
facebook-business>=20.0.0

Versões mínimas. Instala com pip install -r requirements.txt.

6.5 Ferramentas que o servidor expõe

Versão pipeboard (29 ferramentas) , lista oficial do repositório:

1. mcp_meta_ads_get_ad_accounts
2. mcp_meta_ads_get_account_info
3. mcp_meta_ads_get_account_pages
4. mcp_meta_ads_get_campaigns
5. mcp_meta_ads_get_campaign_details
6. mcp_meta_ads_create_campaign
7. mcp_meta_ads_get_adsets
8. mcp_meta_ads_get_adset_details
9. mcp_meta_ads_create_adset
10. mcp_meta_ads_get_ads
11. mcp_meta_ads_create_ad
12. mcp_meta_ads_get_ad_details
13. mcp_meta_ads_get_ad_creatives
14. mcp_meta_ads_create_ad_creative
15. mcp_meta_ads_update_ad_creative
16. mcp_meta_ads_upload_ad_image
17. mcp_meta_ads_get_ad_image
18. mcp_meta_ads_update_ad
19. mcp_meta_ads_update_adset
20. mcp_meta_ads_get_insights
21. mcp_meta_ads_get_login_link
22. mcp_meta_ads_create_budget_schedule
23. mcp_meta_ads_search_interests
24. mcp_meta_ads_get_interest_suggestions
25. mcp_meta_ads_validate_interests
26. mcp_meta_ads_search_behaviors
27. mcp_meta_ads_search_demographics
28. mcp_meta_ads_search_geo_locations
29. mcp_meta_ads_search

Versão playbook Avalanche (14 ferramentas) , recomendada para implementação enxuta:

Para começar, recomenda-se usar a versão pipeboard (mais completa) e depois evoluir para implementação própria conforme necessidade Avalanche.

6.6 Estrutura conceitual do server.py

Um MCP server Python para Marketing API segue este esqueleto. Não é o código completo, é a arquitetura:

# server.py (estrutura conceitual)
import os
from mcp.server import Server
from mcp.types import Tool, TextContent
import httpx
from dotenv import load_dotenv

load_dotenv()

ACCESS_TOKEN = os.getenv("META_ACCESS_TOKEN")
AD_ACCOUNT_ID = os.getenv("META_AD_ACCOUNT_ID")
API_VERSION = os.getenv("META_API_VERSION", "v25.0")
BASE_URL = f"https://graph.facebook.com/{API_VERSION}"

app = Server("meta-ads-mcp")

@app.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(
            name="meta_list_campaigns",
            description="Lista campanhas da conta de anúncios",
            inputSchema={
                "type": "object",
                "properties": {
                    "status": {"type": "string", "enum": ["ACTIVE", "PAUSED", "ALL"]}
                }
            }
        ),
        # ...demais ferramentas
    ]

@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
    async with httpx.AsyncClient(timeout=30.0) as client:
        if name == "meta_list_campaigns":
            url = f"{BASE_URL}/act_{AD_ACCOUNT_ID}/campaigns"
            params = {
                "access_token": ACCESS_TOKEN,
                "fields": "id,name,status,objective,daily_budget"
            }
            if arguments.get("status") and arguments["status"] != "ALL":
                params["effective_status"] = f'["{arguments["status"]}"]'
            response = await client.get(url, params=params)
            return [TextContent(type="text", text=response.text)]
        # ...demais handlers

if __name__ == "__main__":
    app.run()

Pontos arquiteturais:

• Timeout de 30 segundos por chamada (evita loops travados).
• httpx assíncrono para suportar múltiplas chamadas paralelas se o Claude pedir.
• effective_status para filtrar campanhas por status real (não só status que pode estar dessincronizado).
• Toda chamada usa o BASE_URL parametrizado pela versão do .env.

FASE 5 — INSTALAR E REGISTRAR NO CLAUDE CODE

7.1 Instalar dependências

Pasta do projeto, terminal aberto:

cd ~/meta-ads-mcp
pip install -r requirements.txt

Se aparecer erro de permissão, use pip install --user ou crie um virtualenv.

7.2 Testar o servidor isolado

Antes de plugar no Claude, teste o servidor manualmente:

cd ~/meta-ads-mcp
python3 server.py

Servidor sobe e fica aguardando conexão MCP via stdio. Pressione Ctrl+C para parar.

7.3 Registrar o MCP server no Claude Code

Comando oficial Claude Code CLI:

claude mcp add meta-ads -- python3 ~/meta-ads-mcp/server.py

Estrutura do comando:

• claude mcp add , comando de adicionar MCP server.
• meta-ads , nome interno (você escolhe, vira o identificador).
• -- , separador entre nome e comando de execução.
• python3 ~/meta-ads-mcp/server.py , comando que sobe o servidor.

Para verificar se foi registrado:

claude mcp list

Saída esperada: meta-ads listado entre os MCP servers ativos.

7.4 Para versão pipeboard (instalação rápida)

Caminho A: Remote MCP (sem clonar repo)

claude mcp add meta-ads -- npx -y @pipeboard/meta-ads-mcp

Ou conexão direta via URL remota: https://mcp.pipeboard.co/meta-ads-mcp (configure pelo arquivo de config do Claude Desktop ou variável de ambiente do Claude Code).

Caminho B: Local (clone do repo)

git clone https://github.com/pipeboard-co/meta-ads-mcp.git
cd meta-ads-mcp
pip install -r requirements.txt
# Configurar .env com credenciais
claude mcp add meta-ads -- python3 ~/meta-ads-mcp/meta_ads_mcp/server.py

7.5 Testes iniciais

Abra o Claude Code e digite os seguintes prompts. Eles devem funcionar imediatamente se o setup tá correto:

• "Liste minhas campanhas ativas no Meta Ads."
• "Qual o saldo e moeda da minha conta de anúncios?"
• "Mostre o desempenho dos últimos 7 dias."

Se as três funcionarem, está operacional. Pode partir para operação real.

7.6 Erros típicos no primeiro teste

FASE 6 — SEGURANÇA E PROTEÇÃO ANTI-BAN

A diferença entre quem opera tráfego em escala via API e quem leva BM derrubada está aqui. Cada ponto deste é não-negociável.

8.1 Políticas oficiais Meta que regem o jogo

Rate Limits da Marketing API

A Meta tem dois sistemas de rate limit operando em paralelo:

• Platform Rate Limits (Graph API): limite a nível de App = 200 * número de usuários chamadas por hora. Limite a nível de usuário varia individualmente (a Meta não divulga o número exato).
• Business Use Case (BUC) Limits: específicos da Marketing API, calculados por endpoint, variam por tier de acesso (Standard vs Advanced).

Headers que retornam métricas de uso (cheque a cada resposta):

• X-Business-Use-Case-Usage: contém call_count (% de chamadas usadas), total_cputime e total_time (% de processamento usado), estimated_time_to_regain_access (minutos até desbloqueio).
• X-Ad-Account-Usage: contagem específica por conta de anúncios.
• X-App-Usage: contagem a nível de App.

Códigos de erro de rate limiting:

• Erro 32: rate limit de Page ou User atingido.
• Erro 80001: Page account throttled (System/Page tokens).
• Erro 80004: limite de Ads Management atingido (esse é o mais comum em automação).

Recomendação Meta: ao ser throttled, não fazer mais chamadas. Cada chamada extra estende o tempo de bloqueio. Espaçar chamadas, usar filtros para reduzir tamanho de respostas, monitorar headers.

Termos de uso da Marketing API

A Meta não permite:

• Automação da UI do Ads Manager (só Marketing API).
• Compartilhamento de tokens entre Apps ou clientes.
• Uso de tokens em ações fraudulentas (cloak, conteúdo proibido, scams).
• Bypass de rate limits (delays artificiais, IPs rotacionados sistematicamente).

8.2 Special Ad Categories

Se a campanha anuncia produto ou serviço de uma das categorias abaixo, é obrigatório declarar ao criar campanha:

Como declarar via API ao criar campanha:

{
  "name": "Campanha Crédito",
  "objective": "OUTCOME_LEADS",
  "special_ad_categories": ["CREDIT"],
  "status": "PAUSED"
}

Se você não declarar e a Meta detectar que o anúncio cai numa dessas categorias, a campanha é desativada e pode pegar BM. Em política e crédito principalmente, a Meta tem zero tolerância.

Restrições aplicadas automaticamente quando você declara categoria:

• Targeting de idade, gênero e CEP é restrito.
• Targeting por interesses sensíveis fica desabilitado.
• Lookalikes fora dos limites permitidos são rejeitados.

8.3 O que a Meta classifica como suspeito

Padrões detectados pelo algoritmo anti-fraude que levam a flag manual ou banimento automático:

• Spending spike anormal: subir orçamento +500% em poucas horas. Solução: ramp gradual (no máximo +20% ao dia em campanhas estáveis, senão a Meta resseta a fase de aprendizado).
• Criação massiva de campanhas: 50 campanhas criadas em 5 minutos. Solução: espaçar criações, deixar pelo menos alguns segundos entre cada.
• Loops rápidos de chamadas API: ignorar rate limit, fazer 1000 chamadas em 1 minuto. Solução: respeitar delay entre chamadas, monitorar headers.
• IPs múltiplos em janela curta: token usado de IP diferentes em poucos minutos. Solução: rodar MCP server num servidor fixo, não trocar de máquina.
• Anúncios em Special Ad Category sem declarar: já coberto na 8.2.
• Targeting que parece discriminatório em categoria sensível.

8.4 Boas práticas anti-ban (a receita Avalanche)

• System User como único caminho para produção. User Token só em testes manuais.
• Rate limit conservador: timeout 30s no servidor, sem loops ultra-rápidos. Quando o Claude pedir 50 chamadas, o servidor processa de forma sequencial, não bombardeia a API.
• Monitorar headers de uso: armazenar X-Business-Use-Case-Usage em log e alertar quando passar de 60% de uso.
• Spending gradual: novas campanhas começam pausadas, ativam manualmente, sobem orçamento +20% ao dia.
• BM separada por cliente (idealmente): cada cliente da agência tem sua própria BM, com System User próprio. Se um cliente leva BM, não derruba os outros.
• Backup do .env: cópia do token e App Secret em gerenciador de senhas (1Password, Bitwarden).
• Revogação imediata: se suspeitar de comprometimento (token vazou em log, alguém clonou repo com .env), entra em business.facebook.com > System Users > Anular tokens instantaneamente. Token novo em 5 minutos.
• Auditoria de chamadas: o painel Registro de Atividades do App lista todas as chamadas API feitas com aquele App. Revisar semanalmente em busca de anomalias.
• Manter Verificação da Empresa atualizada: BM verificada é pré-requisito para escopos avançados.
• Modo Ao Vivo permanente: App em desenvolvimento limita acesso a admins. Só Ao Vivo permite produção.

8.5 Plano de contingência se a BM cair

Mesmo seguindo tudo, pode acontecer (raro, mas acontece):

1. Não entrar em pânico: ban de BM tem processo de recurso oficial.
2. Acessar o Quality em business.facebook.com/business-quality.
3. Solicitar revisão manual: escolher motivo e enviar dados.
4. Histórico de pagamento limpo ajuda muito (BM com 6+ meses gastando consistentemente tem prioridade).
5. Backup BM: ter uma BM secundária verificada, com System User próprio, é seguro de continuidade. Importante: BMs não podem compartilhar contas de anúncios pessoais, mas podem ter contas próprias.

TROUBLESHOOTING — PROBLEMAS COMUNS E SOLUÇÕES

9.1 Erros de geração de token

"Nenhuma permissão disponível" ao gerar token

• Causa: O App não foi atribuído ao System User como ativo.
• Fix: Em Configurações da Empresa > Contas > Apps, selecione o App, Atribuir pessoas, adicione o System User com Controle total. Volta na tela de gerar token e o App vai aparecer.

App não aparece na lista de apps disponíveis

• Causa: Mesma de cima, ou App está em modo Desenvolvimento sem admin definido.
• Fix: confirmar atribuição do App ao System User na BM, e App em modo Ao Vivo.

App pede verificação por SMS na geração de token

• Causa: comportamento normal e esperado, Meta exige SMS em ações sensíveis.
• Fix: confirmar número de telefone, inserir código recebido. Pronto.

9.2 Erros de configuração do App

"API de Marketing não disponível" no App

• Causa: App foi criado pelo sistema de Use-Cases, não é tipo Business.
• Fix: criar novo App do tipo Empresa (Business). Apps por use-case não suportam Marketing API. Não tem como converter, tem que recriar.

"App não pode sair do modo Desenvolvimento"

• Causa: Política de Privacidade não preenchida, categoria não escolhida, ou BM não verificada.
• Fix: preencher os 3 itens em Configurações > Básico, e fazer Verificação de Empresa na BM.

9.3 Erros de chamada API

Erro 190: Token inválido ou expirado

• Causa: token foi revogado, expirou (caso 60 dias), ou foi gerado para outro App.
• Fix: regenerar token seguindo Fase 3.

Erro 200: Permissão insuficiente

• Causa: token não tem todos os escopos (ads_management, ads_read, business_management).
• Fix: regenerar token com os 3 escopos completos.

Erro 100: Parâmetros inválidos

• Causa: campo obrigatório faltando ou formato errado ao criar campanha/ad set/ad.
• Fix: conferir documentação de cada endpoint. Campos como objective, billing_event, targeting, special_ad_categories (quando aplicável) são obrigatórios.

Erro 17: User request limit reached

• Causa: rate limit de usuário atingido.
• Fix: pausar chamadas, esperar reset (geralmente 1 hora). Reduzir frequência.

Erro 4: Application request limit reached

• Causa: rate limit de App atingido.
• Fix: pausar chamadas. Considerar pedir Advanced Access se for App em produção com volume alto.

Erro 32: Page-level rate limit

• Causa: muito request num token de Page específico.
• Fix: distribuir entre Pages, ou esperar.

Erro 80004: Ads Management limit exceeded

• Causa: limite específico de operações Ads Management atingido (mais comum).
• Fix: reduzir frequência de criação/edição. Esperar reset (geralmente 1h).

9.4 Conta banida ou flagged

BM ou conta de anúncios desativada

• Causa: política violada, comportamento suspeito detectado, ou pagamento.
• Fix:

1. Acessar business.facebook.com/business-quality. 2. Verificar motivo do banimento. 3. Solicitar revisão manual com explicação. 4. Aguardar resposta (5-15 dias úteis em geral).

Spending spike flagged

• Causa: subiu orçamento muito rápido, Meta achou suspeito.
• Fix: voltar orçamento ao normal, aguardar 24-48h. Em geral resolve sozinho. Se persistir, abrir suporte.

Anúncio rejeitado em massa

• Causa: criativo viola política, ou conta sob review.
• Fix: revisar criativo (textos, imagens, claims), verificar se cai em Special Ad Category, ajustar.

9.5 Problemas no MCP Server

"MCP server not found" no Claude Code

• Causa: comando claude mcp add falhou, ou path do server.py errado.
• Fix: rodar claude mcp list, conferir se meta-ads aparece. Se não, executar de novo o claude mcp add com path absoluto correto.

"Module mcp not found" ao subir servidor

• Causa: dependências Python não instaladas.
• Fix: cd ~/meta-ads-mcp && pip install -r requirements.txt.

Servidor sobe mas Claude diz que não tem ferramentas

• Causa: erro no código do server.py na função list_tools(), ou servidor crashando antes de listar.
• Fix: rodar servidor isolado (python3 server.py), conferir logs de erro.

Token funciona no curl mas falha no MCP

• Causa: .env não está sendo carregado pelo server.py, ou variável escrita errado.
• Fix: conferir load_dotenv() no início do server.py, e os.getenv("META_ACCESS_TOKEN") retornando o valor correto. print(os.getenv(...)) para debug.

9.6 Quando NADA funciona

Receita de troubleshooting end-to-end:

1. Curl direto para https://graph.facebook.com/v25.0/me?access_token=TOKEN. Se falhar, é problema de token, regere na Fase 3.
2. Curl em https://graph.facebook.com/v25.0/me/adaccounts?access_token=TOKEN. Se vier vazio, é problema de atribuição de conta na Fase 2.
3. Curl em https://graph.facebook.com/v25.0/act_AD_ACCOUNT_ID/campaigns?access_token=TOKEN. Se falhar com 200, falta ads_read.
4. Se todos os curls funcionam, é problema do MCP server ou Claude Code, não da Meta.

PROMPTS DE EXEMPLO — OPERAÇÃO REAL

Esses prompts foram desenhados para o operador de tráfego usar direto no Claude Code. Cada um aciona uma ou mais ferramentas do MCP server.

10.1 Diagnóstico e visão geral

1. "Lista minhas campanhas ativas e mostra status, orçamento e gasto dos últimos 7 dias."
2. "Qual o saldo, moeda e status da conta de anúncios?"
3. "Quantas campanhas tenho no total, separadas por status (ativas, pausadas, arquivadas)?"
4. "Liste todos os ad sets com gasto acumulado acima de R$1000 nos últimos 30 dias."
5. "Mostra os 10 anúncios com melhor CTR dos últimos 14 dias."

10.2 Análise de performance

1. "Compara o CPA das campanhas ativas, ordenado do menor pro maior."
2. "Qual o desempenho da campanha [NOME] nos últimos 30 dias? CTR, CPC, CPM, gasto total e conversões."
3. "Identifica criativos com fadiga: frequência acima de 3 e CTR caindo nos últimos 7 dias."
4. "Compara performance entre Facebook Feed e Instagram Stories nas campanhas ativas."
5. "Qual ad set tem o melhor ROAS nos últimos 14 dias?"

10.3 Criação e ajuste de campanhas

1. "Cria uma campanha de vendas (objetivo CONVERSIONS) pausada com orçamento diário de R$50."
2. "Cria um ad set para a campanha [ID] com targeting: Brasil, idade 25-45, interesse 'empreendedorismo digital', orçamento diário R$30, otimização para conversão."
3. "Pausa todas as campanhas com CPA acima de R$80 nos últimos 7 dias."
4. "Aumenta em 20% o orçamento das campanhas com ROAS acima de 3."
5. "Reativa o ad set [ID] e ajusta o lance para CPA máximo R$25."

10.4 Criativos e copy

1. "Lista todos os criativos da conta agrupados por imagem/vídeo."
2. "Reescreve a copy do anúncio [ID] mantendo o tom mas trocando o gancho inicial."
3. "Sugere 5 variações de headline para a campanha [NOME] baseadas no que tá performando bem."
4. "Identifica anúncios sem chamada para ação clara e sugere uma."

10.5 Audiências e targeting

1. "Lista minhas audiências customizadas e mostra o tamanho de cada uma."
2. "Sugere interesses adicionais para o ad set [ID] baseado no que tá performando."
3. "Cria audiência lookalike de 1% baseada na audiência [NOME]."
4. "Verifica se algum ad set tá usando targeting que cai em Special Ad Category sem declarar."

10.6 Auditoria e otimização

1. "Faz audit completo da conta: campanhas paradas há mais de 30 dias, ad sets sem gasto há 7 dias, criativos com fadiga, e propõe ações."
2. "Lista todos os anúncios em revisão pela Meta há mais de 24 horas."
3. "Verifica quais campanhas estão no aprendizado e quais já saíram."

10.7 Relatórios para cliente

1. "Monta relatório semanal: resultados por campanha, comparado com semana anterior, com insights e próximos passos."
2. "Gera resumo executivo do mês: investimento, ROAS, principais aprendizados e recomendações."

INTEGRAÇÃO COM A ESTRUTURA AVALANCHE

11.1 Quem opera o MCP no time

No organograma da agência Avalanche, o Denderson Clone (subagente especialista em tráfego pago) é quem opera o MCP server Meta. Ele é o agente IA com expertise em Meta Ads, criativos, ROAS, CPA, escala e otimização.

Fluxo padrão:

1. Chefe pede algo via Telegram, ex: "Como tá performando a campanha do cliente X?"
2. Naia (orquestradora central) recebe a mensagem.
3. Naia delega para o Denderson Clone com a tarefa.
4. Denderson Clone usa o MCP server Meta-Ads via Claude Code, pega os dados, analisa, propõe ações.
5. Naia recebe a resposta do Denderson Clone e entrega pro Chefe.

11.2 Fluxo de operação para cliente Avalanche

Cada cliente da agência Avalanche tem:

• Sua própria BM (verificada, com Verificação de Empresa concluída).
• Seu próprio System User (criado dentro da BM do cliente).
• Seu próprio token permanente (gerado para o System User do cliente).
• Conjunto de variáveis no .env específico do cliente.

Como gerenciar múltiplos clientes:

• Manter .env.cliente1, .env.cliente2, etc. em pastas separadas.
• Rodar instâncias separadas do MCP server, uma por cliente.
• Ou criar um MCP server multi-conta que recebe client_id como argumento e busca o .env correspondente.

11.3 Como o aluno da Comunidade Avalanche replica isso

O aluno que entra na Comunidade Avalanche recebe esse método como template. O passo a passo é:

1. Cria sua própria BM e faz Verificação de Empresa.
2. Cria App tipo Business (Fase 1).
3. Cria System User Admin (Fase 2).
4. Gera token permanente (Fase 3).
5. Clona o repo do MCP server (pode ser pipeboard ou versão Avalanche).
6. Configura .env com suas credenciais.
7. Registra no Claude Code.
8. Começa a operar campanhas via prompts naturais.

A diferença Avalanche é que o aluno não precisa entender de código. O MCP server vem pronto, o .env é template, e os prompts de operação são fornecidos. Aluno só precisa configurar uma vez e operar.

11.4 Integração com CRM Avalanche

Para clientes do CRM Avalanche (white label do GoHighLevel), há uma camada extra:

• Webhook do CRM dispara quando lead chega.
• Lead com tag específica vira evento de conversão personalizado no Pixel da Meta.
• Servidor MCP customizado pode atualizar audiências automaticamente baseado em status do lead no CRM.
• Otimização de campanhas no Meta passa a usar dados do CRM como fonte de verdade.

Essa integração é a próxima fase, fora do escopo deste método base. Documentação separada cobrirá quando estiver implementada.

CHECKLIST FINAL — DO ZERO À OPERAÇÃO

12.1 Pré-requisitos

• Sou admin de uma BM com Verificação de Empresa concluída (status "Verificado").
• Conta de anúncios ativa, com pagamento válido, vinculada à BM.
• Conta de desenvolvedor Meta criada.
• SMS habilitado na conta de desenvolvedor.
• Python 3.10+ instalado.
• Claude Code CLI instalado e funcionando.
• Domínio com Política de Privacidade publicada (HTTPS).

12.2 Fase 1 , App

• App do tipo Empresa (Business) criado no developers.facebook.com.
• App vinculado à BM correta (verificada).
• Produto API de Marketing habilitado no App.
• URL da Política de Privacidade preenchida.
• Email de contato configurado.
• Categoria definida como "Negócio e Páginas".
• App em modo Ao Vivo (não Desenvolvimento).
• App ID anotado.
• App Secret copiado e guardado em gerenciador de senhas.

12.3 Fase 2 , System User

• System User criado com nível Admin.
• Conta de anúncios atribuída ao System User com Controle total.
• App atribuído ao System User com Controle total.
• Páginas atribuídas (se for usar criativos com Page identity).

12.4 Fase 3 , Token

• Token gerado escolhendo o App correto.
• Expiração definida como Nunca (token permanente).
• Permissões: ads_management + ads_read + business_management.
• Verificação SMS confirmada.
• Token copiado e guardado em local seguro.
• Token validado com curl /me (recebe ID válido).
• Token validado com curl /me/adaccounts (recebe lista de contas).

12.5 Fase 4 , MCP Server

• Repositório clonado ou criado em ~/meta-ads-mcp.
• requirements.txt presente com dependências corretas.
• Dependências instaladas (pip install -r requirements.txt).
• Arquivo .env criado com:

- [ ] META_ACCESS_TOKEN - [ ] META_AD_ACCOUNT_ID (sem prefixo act_) - [ ] META_APP_ID - [ ] META_APP_SECRET - [ ] META_API_VERSION (ex: v25.0)

• .env adicionado no .gitignore.
• server.py testado isoladamente (sobe sem erro).

12.6 Fase 5 , Claude Code

• MCP server registrado: claude mcp add meta-ads -- python3 ~/meta-ads-mcp/server.py.
• claude mcp list mostra meta-ads ativo.
• Teste 1: "Liste minhas campanhas ativas" funciona.
• Teste 2: "Qual o saldo da conta?" funciona.
• Teste 3: "Mostra desempenho dos últimos 7 dias" funciona.

12.7 Fase 6 , Segurança

• BM verificada (Verificação de Empresa concluída).
• Token guardado em gerenciador de senhas (não só no .env em disco).
• App em modo Ao Vivo.
• Política de Privacidade ainda válida e acessível.
• .env NÃO commitado em repositório público.
• Script de monitoramento de headers X-Business-Use-Case-Usage (opcional mas recomendado).
• Plano de contingência: BM secundária ou backup de token preparado.

FONTES OFICIAIS CONSULTADAS

13.1 Documentação oficial Meta

• Marketing API Overview: https://developers.facebook.com/docs/marketing-apis/
• System Users: https://developers.facebook.com/docs/marketing-api/system-users
• Marketing API Reference v25.0: https://developers.facebook.com/docs/marketing-api/reference/v25.0
• Insights endpoint: https://developers.facebook.com/docs/marketing-api/insights
• Graph API Rate Limiting: https://developers.facebook.com/docs/graph-api/overview/rate-limiting
• Marketing API Access Tiers: https://developers.facebook.com/docs/marketing-api/access
• Marketing API Error Reference: https://developers.facebook.com/docs/marketing-api/error-reference
• Special Ad Categories: https://developers.facebook.com/docs/marketing-api/buying-api/special-ad-categories/
• Graph API Changelog: https://developers.facebook.com/docs/graph-api/changelog

13.2 Anúncios oficiais Meta

• "Meta opens its ad ecosystem to third-party AI tools" (Digiday, 29/04/2026): cobertura do open beta global do Meta ads AI connectors. URL Digiday confirmada como fonte do anúncio.
• Meta Business News (about.meta.com): texto oficial do anúncio do open beta, mencionando MCP server e CLI oficiais Meta.

13.3 Repositórios e ferramentas

• Pipeboard meta-ads-mcp: https://github.com/pipeboard-co/meta-ads-mcp. MCP server pronto para Marketing API com 29 ferramentas. Licença Business Source License 1.1 (vira Apache 2.0 em jan/2029).
• Remote MCP Pipeboard: https://mcp.pipeboard.co/meta-ads-mcp. Versão hospedada do MCP server (sem setup local).

13.4 Especificação MCP

• Model Context Protocol (Anthropic): protocolo aberto que define como modelos IA conversam com sistemas externos via servidor intermediário.

13.5 Playbook Avalanche referência

• "PLAYBOOK Meta Marketing API · Integração Completa com Claude via MCP Server" (abril 2026): documento interno cruzado com documentação oficial Meta nesta consolidação.

13.6 Notas sobre divergências e validações

Na consolidação deste método, todas as afirmações do playbook interno foram cruzadas com a documentação oficial Meta. Os pontos centrais batem com a documentação oficial:

• Necessidade de App tipo Business (não Use-Case): confirmado.
• System User como caminho recomendado para integrações server-to-server: confirmado.
• Token permanente sem expiração via System User: confirmado pela documentação Meta sobre System Users.
• Permissões ads_management, ads_read, business_management: confirmadas como o conjunto base para Marketing API.
• Versão v25.0 ativa em abril/2026: confirmada na referência da Marketing API.
• Rate limits e códigos de erro listados (32, 100, 190, 200, 80004): confirmados na Error Reference oficial e na documentação de Rate Limiting.
• Special Ad Categories obrigatórias: confirmadas nos guias oficiais de buying API.
• AI connectors em open beta (29/04/2026): confirmado pelo anúncio Digiday e referências do anúncio Meta.

Não houve divergências materiais entre o playbook interno e a documentação oficial. O playbook é fiel ao processo oficial Meta. As adições deste método sobre o playbook original são:

• Inclusão do contexto AI connectors (anúncio 29/04/2026) e diferenciação entre Caminho A (conector oficial Meta) e Caminho B (Marketing API direto).
• Detalhamento de Rate Limits oficiais (Platform vs BUC), headers de monitoramento, códigos de erro específicos.
• Special Ad Categories com lista completa e exemplo de declaração.
• Lista das 29 ferramentas do projeto pipeboard-co/meta-ads-mcp como referência open source.
• Boas práticas anti-ban derivadas da combinação do playbook + termos oficiais Meta + relatos comunitários sobre comportamentos suspeitos detectados.

CHECKPOINT FINAL DA NAIA

Este método cobre o caminho completo, do zero à operação real, para um operador de tráfego ou agência rodar Meta Ads via Claude Code com Marketing API direto.

A combinação que faz funcionar em produção:

1. App tipo Business (não Use-Case).
2. System User Admin com token permanente.
3. MCP server rodando local ou remoto (pipeboard ou customizado).
4. Claude Code registrado com claude mcp add.
5. Rate limits respeitados e Special Ad Categories declaradas.
6. BM verificada com plano de contingência.

A partir daqui, o time Avalanche replica esse método para cada cliente e cada subagente da operação. O Denderson Clone passa a operar campanhas via prompts naturais, com 14-29 ferramentas expostas pelo MCP. O Chefe pede em linguagem natural, a Naia delega, o Denderson Clone executa via Claude Code.

Tráfego pago opera em escala, sem clique manual no Ads Manager, dentro dos termos oficiais Meta, com BM segura.

// fim do tutorial . metodo avalanche . meta + claude . 30 abr 2026