KonQuest Meta Ads MCP

Sistema operacional supervisionado de Meta Ads para Claude Code - 57 ferramentas para gerenciamento de campanhas, anúncios com múltiplos ativos, segmentação, diagnóstico de pixel, catálogos e barreiras de segurança

GitHub

Experimente este MCPPatrocinado

Documentação

KonQuest Meta Ads MCP

Sistema Operacional Supervisionado de Meta Ads para Claude Code. Você pode encontrar a versão premium aqui: https://farasokster.gumroad.com/l/konquest-meta-ads-mcp-premium

Modelo Open-Core

O KonQuest Meta Ads MCP utiliza um modelo open-core:

Público (este repositório) - 57 ferramentas, licença MIT:

CRUD completo para campanhas, conjuntos de anúncios e anúncios
Criação de anúncios multi-asset (vídeo + imagem estática, multi-dimensão)
Upload e recuperação de imagens
Duplicação de campanhas e conjuntos de anúncios
Insights e análises em massa entre contas
Diagnóstico de Pixel e rastreamento (5 ferramentas)
Suporte a Catálogos e DPA (6 ferramentas, incluindo criação/atualização de conjuntos de produtos)
Kit completo de segmentação (6 ferramentas)
Verificador de prontidão de configuração (42+ verificações com instruções de correção)
Pipeline de validação, aplicação de convenção de nomenclatura, verificação pós-escrita
Camadas de segurança, limite de taxa, referências de rollback
215 testes automatizados

Pacote Premium - adiciona 41 ferramentas:

Motor de otimização consultivo (filas de revisão, aprendizado, experimentos, controlador de orçamento, rotação de criativos)
Inteligência de Vault e geração de cópia (voz da marca, segmentação ICP, seleção de conceitos)
QA de idioma grego (detecção de Greeklish, verificações ortográficas)
Suíte de automação (diagnósticos, operações em massa, auditoria de contas)
Bootstrap de Vault (15 arquivos de modelo por cliente)
Testes e avaliações premium

O pacote premium está disponível separadamente. As ferramentas públicas funcionam totalmente sem ele.

O Que Torna Isso Diferente

Testado em produção em mais de 37 campanhas de clientes com orçamentos reais e casos extremos reais
Não é um wrapper - inclui motor de otimização, portões de segurança, validadores e rollback
Integrado ao Vault - lê inteligência do cliente (ICPs, voz da marca, ângulos) para gerar melhores anúncios
QA de idioma grego integrado (adaptável a qualquer validação de idioma)
Todos os anúncios criados PAUSADOS - nada entra no ar sem aprovação explícita do operador
Supervisionado, não autônomo - o operador confirma cada escrita, cada ativação, cada mudança de orçamento

Classificação de Ferramentas

Classificação	Quantidade	Descrição
seguro-para-produção	38	Acesso somente leitura a dados. Sem escritas na API, sem mudanças de estado local.
somente-supervisionado	29	Operações de escrita/exclusão que exigem aprovação do operador antes da execução.
somente-consultivo	31	Gera recomendações, planos, cópias, diagnósticos. Sem escritas na API do Meta. Pode escrever arquivos locais.
Total: 98 registradas

Arquitetura

meta_ads_mcp/
  core/          # 66 tools - API read/write operations
  engine/        # 32 tools - optimization, review, learning, experiments
  validators/    # Quality gates (compliance, creative specs, tracking, structure)
  safety/        # Rate limiting, rollback, duplicate checking, file locks, tier access
  ingestion/     # Internal: video manifest management
  reporting/     # Internal: not currently active (see Non-Shipped Code)

Categorias de Ferramentas

Categoria	Ferramentas	Descrição
Gerenciamento de Contas	6	Saúde do token, contas de anúncios, páginas, identidade IG, descoberta
Campanhas	4	Criar, ler, atualizar campanhas
Conjuntos de Anúncios	4	Criar, ler, atualizar conjuntos de anúncios com segmentação
Anúncios	4	Criar, ler, atualizar anúncios
Criativos	3	Criar, ler criativos de anúncios
Insights e Análises	1	Dados de desempenho com normalização ciente de arquétipo
Pixels e Rastreamento	5	Saúde do pixel, diagnóstico de eventos, eventos de teste, CAPI
Catálogos e DPA	6	Catálogos de produtos, feeds, conjuntos de produtos, validação
Públicos	1	Listagem de públicos personalizados
Segmentação	3	Pesquisa de interesses, comportamentos e geográfica
Gerenciamento de Vídeo	3	Upload (simples + retomável) e status de processamento
Construtor de Anúncios	1	Criação de anúncios multi-asset com aplicação de portão IG
Motor de Cópia	2	Geração e validação de cópia de anúncio orientada por Vault
Convenção de Nomenclatura	1	Esquema de nomenclatura aplicado para todos os objetos
Automação e Diagnósticos	6	QA grego, diagnóstico completo, operações em massa, auditoria de contas
Vault e Inteligência	2	Leitor de vault do cliente, seleção de conceitos
Motor de Otimização	4	Ciclos de otimização, planejamento de lançamento, pacotes de execução
Corredor de Mutação	2	Mudanças de orçamento/segmentação com verificação
Ativação e Rollback	4	Mudanças de status e desfazer com verificações de pré-voo
Fila de Revisão	7	Fila de revisão do operador, snapshots de resultados, resumos
Camada de Aprendizado	5	Memória de políticas, avaliação de resultados, ciclos de aprendizado
Experimentos	7	Testes A/B, controlador de orçamento, rotação de criativos, escalonamento
Geração de Cópia	2	Cadeia de cópia automática, cópia grega fundamentada em vault

Recursos do Motor

Loops de otimização - mudança automatizada de orçamento com base em sinais de desempenho
Gerenciamento de experimentos - rastreamento de testes A/B com significância estatística
Controladores de orçamento - previnem gastos excessivos com limites diários/vitais configuráveis
Rotação de criativos - detecção de fadiga e gatilhos automáticos de atualização de criativos
Aprendizado de políticas - rastreia resultados de ações e adapta a confiança ao longo do tempo
Portão de nomenclatura - aplicação rígida de convenções de nomenclatura antes de qualquer escrita na API

Recursos de Segurança

Limite de taxa - respeita os limites de taxa da API do Meta com backoff
Rollback - desfaz mudanças recentes com diário de execução
Verificação de duplicatas - previne campanhas/anúncios duplicados acidentais
Bloqueios de arquivo - acesso concorrente seguro ao armazenamento do vault
Acesso por camadas - camadas de segurança por conta (sandbox, padrão, produção)

Suíte de Validadores

Validador de conformidade - pré-verificação da política de anúncios do Meta
Validador de especificações de criativos - validação de dimensões e formatos de imagem/vídeo
Validador de rastreamento - verificação de pixel e eventos antes do lançamento
Validador de estrutura - verificações de consistência da estrutura da campanha
Validador operacional - verificações de sanidade de orçamento, cronograma e segmentação

Código Não Enviado

Código que existe no repositório, mas NÃO faz parte da superfície ativa de ferramentas:

reporting/templates.py, reporting/formatter.py - não importados em tempo de execução, sem geração ativa de relatórios
evals/ - stubs de avaliação internos, não voltados ao operador
Helpers internos (não são ferramentas MCP): identity.py (resolução IG), api.py (cliente HTTP), auth.py (verificação de token), utils.py (helpers de formato), safety/ (limitador de taxa, rollback, deduplicação), validators/ (pipeline de validação pré-escrita)

Configuração

1. Instalação

cd meta-ads-mcp
uv sync

2. Variáveis de Ambiente

Copie .env.example para .env e preencha com seus valores:

cp .env.example .env

Obrigatório:

META_ACCESS_TOKEN - token de acesso da API de Marketing do Meta (recomendado token de usuário de sistema)

Opcional:

META_APP_SECRET - para appsecret_proof (recomendado para produção)
META_APP_ID - ID do aplicativo Meta
VAULT_PATH - caminho para o diretório do seu vault de marketing (padrão: ~/marketing-vault)

3. Configuração do MCP

Adicione à configuração do MCP do seu Claude Code (.mcp.json):

{
  "mcpServers": {
    "meta-ads": {
      "command": "uv",
      "args": ["--directory", "/path/to/meta-ads-mcp", "run", "python", "-m", "meta_ads_mcp"],
      "env": {
        "META_ACCESS_TOKEN": "your_token_here",
        "VAULT_PATH": "/path/to/your/marketing-vault"
      }
    }
  }
}

4. Estrutura do Vault (Opcional)

Se estiver usando a integração com vault para inteligência do cliente:

your-vault/
  01_CLIENTS/{client-slug}/
    00-profile.md        # Account IDs, pixel, page, IG
    02-icp-personas.md   # Target audience profiles
    04-brand-voice.md    # Tone, language, style rules
    05-messaging-house.md # Angles, value props
    08-objections.md     # Objections + bias deployment
    matrix.md            # Decision Matrix
  02_COMPETITORS/{slug}/
    landscape.md         # Competitive landscape

Testes

uv run --extra dev python -m pytest tests/ -v
# Public package: 215 passed | Full (with premium): 246 passed

Licença

MIT - veja LICENSE.