meta-ads-mcp

Servidor MCP próprio para criar e gerenciar campanhas completas na Meta (Facebook/Instagram) via Marketing API — campanhas, conjuntos de anúncios com público-alvo, orçamentos, criativos, anúncios, públicos personalizados/lookalike, lead gen, regras automatizadas e relatórios. 51 ferramentas.

Pré-requisitos na Meta

Você precisa de duas coisas: um token de acesso e o ID da conta de anúncios.

1. App com a Marketing API

Em developers.facebook.com/apps, tenha (ou crie) um app e adicione o produto API de Marketing (Painel → Produtos → Configurar).

⚠️ Atenção: apps criados só para "Login do Facebook" não oferecem o caso de uso da Marketing API. O app precisa ser do tipo que lista "API de Marketing" nos produtos disponíveis. Se o seu não tiver, use outro app ou crie um novo.

2. Token de System User (recomendado — não expira)

Um token de System User é permanente e ideal para gerenciar um portfólio de contas. No Business Manager → Usuários do sistema:

1. Crie um System User com função Admin (ex: nome MCP Automation).
2. Atribua os ativos a ele (botão Adicionar ativos): a(s) conta(s) de anúncios (com Controle total) e as Páginas (para criar criativos).
3. Vincule o app ao System User: em Configurações do negócio → Apps → seu app → Pessoas → Atribuir pessoas, adicione o System User com Gerenciar app. Este passo é o que destrava as permissões do token — sem ele, a geração do token mostra "Nenhuma permissão disponível".
4. De volta ao System User, clique em Gerar token, selecione o app (o que tem a Marketing API), expiração Nunca, e marque as permissões:
   • ads_management (criar/editar campanhas)
   • ads_read (insights)
   • business_management
   • pages_show_list e pages_read_engagement (Páginas/criativos) — se disponíveis
   • leads_retrieval (baixar leads de formulários) — se for usar lead gen
5. Copie o token (começa com EAA...). Ele só aparece uma vez.

3. ID da conta de anúncios

No Ads Manager, no seletor de contas. Aceita com ou sem o prefixo act_ (ex: act_1234567890 ou 1234567890).

Instalação (Claude Code)

Não precisa clonar nada — o pacote roda direto via npx. Registre com um comando, passando o seu token e a conta de anúncios:

claude mcp add meta-ads \
  --env META_ACCESS_TOKEN=SEU_TOKEN \
  --env META_AD_ACCOUNT_ID=1234567890 \
  -- npx -y @creativeproject/meta-ads-mcp

Pronto. O Claude Code sobe e derruba o servidor sozinho a cada sessão — nada fica rodando em background. Reinicie a sessão e as ferramentas do meta-ads estarão disponíveis.

Outros clientes MCP (Claude Desktop, Cursor, etc.)

Adicione ao mcpServers do seu cliente:

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "@creativeproject/meta-ads-mcp"],
      "env": {
        "META_ACCESS_TOKEN": "SEU_TOKEN",
        "META_AD_ACCOUNT_ID": "1234567890"
      }
    }
  }
}

Configuração (variáveis de ambiente)

Só META_ACCESS_TOKEN é obrigatória. As demais são opcionais.

| Variável | Obrig. | Descrição | |---|---|---| | META_ACCESS_TOKEN | ✓ | Token da Marketing API (ver pré-requisitos acima) | | META_AD_ACCOUNT_ID | | Conta padrão (toda ferramenta também aceita account_id por chamada). Sem ela, informe a conta em cada chamada | | META_ACCOUNT_TOKENS | | Multi-BM: JSON {"act_111": "tokenA", "act_222": "tokenB"} — contas listadas usam o token próprio, as demais usam o padrão | | META_MAX_DAILY_BUDGET | | Guard-rail: teto de orçamento diário em centavos; criações/atualizações acima disso são rejeitadas | | META_MAX_LIFETIME_BUDGET | | Idem para orçamento total | | META_API_VERSION | | Versão da Graph API (padrão v23.0) | | MCP_HTTP_AUTH_TOKEN | | Obrigatório apenas para o modo HTTP — Bearer token das requisições | | MCP_HTTP_PORT | | Porta do modo HTTP (padrão 3535) |

Modo HTTP remoto (opcional)

Para hospedar (Railway, Fly.io, VPS) e usar no claude.ai ou compartilhar com a equipe:

MCP_HTTP_AUTH_TOKEN=um-segredo-forte npx @creativeproject/meta-ads-mcp
# na verdade, o modo HTTP roda pelo entrypoint http — ver "Desenvolvimento" abaixo

O servidor se recusa a iniciar em modo HTTP sem MCP_HTTP_AUTH_TOKEN.

Desenvolvimento (clonando o repositório)

Só necessário se você quer contribuir ou modificar o código:

git clone https://github.com/wayter95/meta-ads-mcp.git
cd meta-ads-mcp
npm install
cp .env.example .env   # preencha as credenciais
npm run dev            # stdio com watch
npm run start:http     # modo HTTP remoto
npm test               # 34 testes (unit + integração do servidor MCP em memória)
npm run inspector      # debug visual com o MCP Inspector

Documentação

• docs/TOOLS.md — referência completa das 58 ferramentas, parâmetro por parâmetro.
• Guia embutido para a IA consumidora — o servidor entrega instruções de uso à IA de três formas: instructions no handshake MCP (regras críticas resumidas), resource meta-ads://guide e ferramenta get_usage_guide (guia completo: fluxos, regras, erros comuns).

Ferramentas

Conta, ativos e operação

list_ad_accounts · get_ad_account · list_pages · list_pixels · list_instagram_accounts · get_rate_limit_status (uso de rate limit observado nos headers) · get_change_history (auditoria: quem mudou o quê na conta)

Campanhas

create_campaign (com validate_only para dry run) · update_campaign · list_campaigns · get_campaign · delete_campaign

Ad sets (público-alvo e orçamento)

create_ad_set — segmentação completa: geo (país/estado/cidade/raio/pin), idade, gênero, interesses, comportamentos, públicos personalizados, idiomas, posicionamentos, Advantage+ Audience; orçamento diário/vitalício; pixel/evento de conversão; validate_only · update_ad_set · list_ad_sets · get_ad_set · delete_ad_set · estimate_audience_size

Busca de segmentação

search_targeting_interests · search_geo_locations · search_targeting (comportamentos, demografia, idiomas, cargos)

Criativos

upload_image (arquivo ou URL) · upload_video · get_video_status · create_ad_creative (imagem/vídeo + texto, CTA, UTMs) · create_flexible_ad_creative (Advantage+ creative — até 5 variações de texto/título/descrição e múltiplas mídias via asset_feed_spec) · create_carousel_creative (2–10 cartões) · list_ad_creatives · preview_ad_creative

Anúncios

create_ad (com validate_only) · update_ad · list_ads · get_ad (inclui feedback de reprovação) · delete_ad

Públicos

create_website_custom_audience (Pixel: evento, URL, retenção) · create_customer_list_audience · add_users_to_customer_list / remove_users_from_customer_list (normalização + hash SHA-256 local — nenhum dado em texto puro sai da máquina) · create_lookalike_audience (1%–20%) · list_custom_audiences · get_custom_audience · delete_custom_audience

Lead gen (formulários instantâneos)

create_leadgen_form · list_leadgen_forms · get_leads (baixa os leads capturados) — o Page Access Token é resolvido automaticamente.

Regras automatizadas

create_ad_rule (ex: "pausar ad set se gasto > X sem resultados", "notificar se CPC > Y") · list_ad_rules · update_ad_rule · delete_ad_rule

Testes A/B (ad studies)

create_ab_test — split test formal da Meta: 2–4 células com públicos estatisticamente isolados (sem sobreposição), cada uma com seus ad sets ou campanhas e percentual do público (≥10% cada, soma ≤100%), com objetivo medido por Pixel · list_ab_tests · get_ab_test (configuração e células) · get_ab_test_results (métricas lado a lado por célula no período do teste) · update_ab_test (renomear/encerrar antecipadamente) · delete_ab_test. Requer META_BUSINESS_ID (ou business_id por chamada).

Orquestração

create_full_campaign — campanha completa em uma chamada: campanha → ad set (público + orçamento) → criativo (aceita creative_id existente, image_url, arquivo local ou vídeo) → anúncio. Com rollback automático: se qualquer etapa falhar, a campanha já criada é excluída para não deixar estrutura órfã.

Relatórios

get_insights — qualquer nível, períodos predefinidos/customizados, breakdowns (idade, gênero, país, plataforma, posição), granularidade diária/semanal.

Comportamentos de segurança e resiliência

• Tudo nasce PAUSED — nada gasta dinheiro até ativação explícita.
• validate_only em create_campaign/create_ad_set/create_ad: a Meta valida tudo sem criar nada.
• Guard-rail de orçamento via META_MAX_DAILY_BUDGET/META_MAX_LIFETIME_BUDGET (proteção contra erro de digitação em centavos).
• Retry automático com backoff (2s → 6s → 15s) em erros de throttling da Meta (códigos 4, 17, 32, 613, 80xxx); uso de rate limit consultável via get_rate_limit_status.
• Paginação em todas as listagens via cursor after.
• Hashing SHA-256 local de dados de clientes antes de qualquer envio à Meta.
• HTTP remoto só com autenticação — recusa iniciar sem Bearer token configurado.

Multi-conta e multi-BM

• Um BM, várias contas: um token de System User com os ativos atribuídos resolve — toda ferramenta aceita account_id por chamada.
• Vários BMs: mapeie tokens por conta em META_ACCOUNT_TOKENS. As ferramentas de objeto (update_*, get_*, delete_*) aceitam account_id opcional para resolver o token correto.

Fluxo típico

1. search_geo_locations("São Paulo")           → city_ids
2. search_targeting_interests("marketing")     → interest_ids
3. estimate_audience_size(...)                 → valida o público
4. create_full_campaign(...)                   → tudo criado PAUSED, com rollback
5. preview_ad_creative(creative_id)            → conferir visual
6. update_campaign(status: ACTIVE)             → ativar
7. create_ad_rule("pausar se CPA > X")         → guarda permanente
8. get_insights(...)                           → acompanhar desempenho

Notas importantes

• Orçamentos em centavos: 5000 = R$ 50,00.
• CBO vs. ABO: orçamento na campanha ou nos ad sets, nunca nos dois (o create_full_campaign valida isso).
• special_ad_categories é obrigatório declarar (vazio se não se aplica).
• UE (DSA): anúncios na União Europeia exigem dsa_beneficiary/dsa_payor no ad set.
• Vídeos processam de forma assíncrona — confira com get_video_status antes de usar no criativo.