KonQuest Meta Ads MCP

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 multi-asset (video + imagen estática, multi-dimensió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 de catálogos y DPA (6 herramientas, incluyendo creación/actualización de conjuntos de productos)
• Kit completo de segmentación (6 herramientas)
• Verificador de preparación (42+ comprobaciones con instrucciones de corrección)
• Pipeline de validación, aplicación de convenciones de nombres, verificación post-escritura
• Niveles de seguridad, límites de tasa, referencias de rollback
• 215 pruebas automatizadas

Paquete premium - añade 41 herramientas:

• Motor de optimización asesor (colas de revisión, aprendizaje, experimentos, gobernador de presupuesto, rotación creativa)
• Inteligencia de vault y generación de copys (voz de marca, segmentación ICP, selección de conceptos)
• QA en idioma griego (detección de Greeklish, comprobaciones ortográficas)
• Suite de automatización (diagnósticos, operaciones masivas, auditoría de cuentas)
• Bootstrap de vault (15 archivos de plantilla por cliente)
• Pruebas y evaluaciones premium

El paquete premium está disponible por separado. Las herramientas públicas funcionan completamente sin él.

Qué Hace Esto Diferente

• Probado en producción en más de 37 campañas de clientes con presupuestos reales y casos límite reales
• No es un wrapper - incluye motor de optimización, puertas de seguridad, validadores y rollback
• Integrado con vault - lee inteligencia del cliente (ICPs, voz de marca, ángulos) para generar mejores anuncios
• QA de idioma griego integrado (adaptable a cualquier validación de idioma)
• Todos los anuncios se crean EN PAUSA - nada se publica sin 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

Clasificación	Cantidad	Descripción
seguro para producción	38	Acceso a datos de solo lectura. Sin escrituras API, sin cambios de estado local.
solo supervisado	29	Operaciones de escritura/eliminación que requieren aprobación del operador antes de la ejecución.
solo asesoramiento	31	Genera recomendaciones, planes, copys, diagnósticos. Sin escrituras a la API de Meta. Puede escribir archivos locales.
Total: 98 registradas

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

Categoría	Herramientas	Descripción
Gestión de Cuentas	6	Salud del token, cuentas publicitarias, páginas, identidad IG, descubrimiento
Campañas	4	Crear, leer, actualizar campañas
Conjuntos de Anuncios	4	Crear, leer, actualizar conjuntos de anuncios con segmentación
Anuncios	4	Crear, leer, actualizar anuncios
Creativos	3	Crear, leer creativos publicitarios
Insights y Analítica	1	Datos de rendimiento con normalización consciente de arquetipos
Píxeles y Seguimiento	5	Salud del píxel, diagnóstico de eventos, eventos de prueba, CAPI
Catálogos y DPA	6	Catálogos de productos, feeds, conjuntos de productos, validación
Audiencias	1	Listado de audiencias personalizadas
Segmentación	3	Búsqueda de intereses, comportamientos y geo
Gestión de Video	3	Carga (simple + reanudable) y estado de procesamiento
Ad Builder	1	Creación de anuncios multi-asset con aplicación de la puerta de IG
Motor de Copys	2	Generación y validación de copys publicitarios impulsada por vault
Convención de Nombres	1	Esquema de nombres obligatorio para todos los objetos
Automatización y Diagnósticos	6	QA griego, diagnóstico completo, operaciones masivas, auditoría de cuentas
Vault e Inteligencia	2	Lector de vault del cliente, selección de conceptos
Motor de Optimización	4	Ciclos de optimización, planificación de lanzamiento, paquetes de ejecución
Corredor de Mutación	2	Cambios de presupuesto/segmentación con verificación
Activación y Rollback	4	Cambios de estado y deshacer con comprobaciones previas
Cola de Revisión	7	Cola de revisión del operador, instantáneas de resultados, resúmenes
Capa de Aprendizaje	5	Memoria de políticas, evaluación de resultados, ciclos de aprendizaje
Experimentos	7	Pruebas A/B, gobernador de presupuesto, rotación creativa, escalado
Generación de Copys	2	Cadena de copys automática, copys griegos basados en vault

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
• Gobernadores de presupuesto - evitan el sobre-gasto con límites diarios/de por vida configurables
• Rotación creativa - detección de fatiga y activación automática de actualización creativa
• Aprendizaje de políticas - rastrea resultados de acciones y adapta la confianza con el tiempo
• Puerta de nombres - aplicación estricta de convenciones de nombres antes de cualquier escritura API

Características de Seguridad

• Límites de tasa - respeta los límites de tasa de la API de Meta con backoff
• Rollback - deshace cambios recientes con diario de ejecución
• Verificación de duplicados - previene campañas/anuncios duplicados accidentales
• Bloqueos de archivos - acceso concurrente seguro al almacenamiento del vault
• Acceso por niveles - niveles de seguridad por cuenta (sandbox, estándar, producción)

Suite de Validadores

• Validador de cumplimiento - pre-comprobación de políticas publicitarias de Meta
• Validador de especificaciones creativas - validación de dimensiones y formatos de imagen/video
• Validador de seguimiento - verificación de píxeles y eventos antes del lanzamiento
• Validador de estructura - comprobaciones de consistencia de la estructura de campañas
• Validador operacional - comprobaciones de presupuesto, programación y segmentación

Código No Incluido en el Producto

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

• reporting/templates.py, reporting/formatter.py - no se importan en tiempo de ejecución, sin generación de informes activa
• evals/ - stubs de evaluación internos, no orientados al operador
• Helpers internos (no son herramientas MCP): identity.py (resolución de IG), api.py (cliente HTTP), auth.py (verificación de tokens), utils.py (helpers de formato), safety/ (limitador de tasa, rollback, 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 completa 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 de 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 vault 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 del Vault (Opcional)

Si usas la integración de vault para la inteligencia del 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.