KonQuest Meta Ads MCP

Sistema operativo supervisado de Meta Ads para Claude Code. Puedes encontrar la versión premium aquí: https://farasokster.gumroad.com/l/konquest-meta-ads-mcp-premium

Modelo Open-Core

KonQuest Meta Ads MCP utiliza un modelo open-core:

Público (este repositorio) - 57 herramientas, licencia MIT:

• CRUD completo para campañas, conjuntos de anuncios y anuncios

• Creación de anuncios multiactivo (vídeo + imagen estática, multidimensión)

• Carga y recuperación de imágenes

• Duplicación de campañas y conjuntos de anuncios

• Insights y analítica masiva entre cuentas

• Diagnóstico de píxeles y seguimiento (5 herramientas)

• Soporte para catálogos y DPA (6 herramientas, incluyendo creación/actualización de conjuntos de productos)

• Kit de herramientas de segmentación completo (6 herramientas)

• Comprobador de preparación de configuración (más de 42 comprobaciones con instrucciones de corrección)

• Pipeline de validación, cumplimiento de nomenclatura, verificación post-escritura

• Niveles de seguridad, limitación de tasa, referencias de reversión

• 215 pruebas automatizadas

Paquete Premium - añade 41 herramientas:

• Motor de optimización consultivo (colas de revisión, aprendizaje, experimentos, regulador de presupuesto, rotación de creatividades)

• Inteligencia de bóveda y generación de textos (voz de marca, segmentación ICP, selección de conceptos)

• Control de calidad del idioma griego (detección de Greeklish, comprobaciones ortográficas)

• Suite de automatización (diagnóstico, operaciones masivas, auditoría de cuentas)

• Bootstrap de bóveda (15 archivos de plantilla por cliente)

• Pruebas y evaluaciones premium

Paquete premium disponible por separado. Las herramientas públicas funcionan completamente sin él.

Qué lo hace diferente

• Probado en producción en más de 37 campañas de clientes con presupuestos reales y casos extremos reales

• No es un wrapper - incluye motor de optimización, puertas de seguridad, validadores y reversión

• Integrado con la bóveda - lee la inteligencia del cliente (ICP, voz de marca, ángulos) para generar mejores anuncios

• Control de calidad del idioma griego integrado (adaptable a cualquier validación de idioma)

• Todos los anuncios se crean en PAUSA - nada se publica sin la aprobación explícita del operador

• Supervisado, no autónomo - el operador confirma cada escritura, cada activación, cada cambio de presupuesto

Clasificación de herramientas

Arquitectura

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)

Categorías de herramientas

Características del motor

• Bucles de optimización - cambio automático de presupuesto basado en señales de rendimiento

• Gestión de experimentos - seguimiento de pruebas A/B con significancia estadística

• Reguladores de presupuesto - evitan el gasto excesivo con límites diarios/totales configurables

• Rotación de creatividades - detección de fatiga y disparadores automáticos de actualización de creatividades

• Aprendizaje de políticas - rastrea los resultados de las acciones y adapta la confianza con el tiempo

• Puerta de nomenclatura - cumplimiento estricto de las convenciones de nombres antes de cualquier escritura en la API

Características de seguridad

• Limitación de tasa - respeta los límites de tasa de la API de Meta con retroceso

• Reversión - deshace cambios recientes con diario de ejecución

• Comprobación de duplicados - evita campañas/anuncios duplicados accidentales

• Bloqueos de archivos - acceso concurrente seguro al almacenamiento de la bóveda

• Acceso por niveles - niveles de seguridad por cuenta (sandbox, estándar, producción)

Suite de validadores

• Validador de cumplimiento - comprobación previa de la política publicitaria de Meta

• Validador de especificaciones creativas - validación de dimensiones y formato de imagen/vídeo

• Validador de seguimiento - verificación de píxeles y eventos antes del lanzamiento

• Validador de estructura - comprobaciones de consistencia de la estructura de la campaña

• Validador operativo - comprobaciones de cordura de presupuesto, programación y segmentación

Código no distribuido

Código que existe en el repositorio pero NO es parte de la superficie de herramientas activa:

• reporting/templates.py, reporting/formatter.py - no importado en tiempo de ejecución, sin generación de informes activa

• evals/ - stubs de evaluación interna, no orientados al operador

• Ayudantes internos (no herramientas MCP): identity.py (resolución de IG), api.py (cliente HTTP), auth.py (verificación de token), utils.py (ayudantes de formato), safety/ (limitador de tasa, reversión, deduplicación), validators/ (pipeline de validación pre-escritura)

Configuración

1. Instalación

cd meta-ads-mcp
uv sync

2. Variables de entorno

Copia .env.example a .env y rellena tus valores:

cp .env.example .env

Requerido:

• META_ACCESS_TOKEN - Token de acceso a la API de Marketing de Meta (se recomienda token de usuario del sistema)

Opcional:

• META_APP_SECRET - para appsecret_proof (recomendado para producción)

• META_APP_ID - ID de la aplicación de Meta

• VAULT_PATH - ruta a tu directorio de bóveda de marketing (por defecto ~/marketing-vault)

3. Configuración de MCP

Añade a tu configuración de MCP de 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. Estructura de la bóveda (Opcional)

Si utilizas la integración de bóveda para inteligencia de 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

Pruebas

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

Licencia

MIT - ver LICENSE.