KonQuest Meta Ads MCP

Операционная система для управления Meta Ads под надзором для Claude Code. Премиум-версию можно найти здесь: https://farasokster.gumroad.com/l/konquest-meta-ads-mcp-premium

Модель Open-Core

KonQuest Meta Ads MCP использует модель open-core:

Публичная версия (этот репозиторий) — 57 инструментов, лицензия MIT:

• Полный CRUD для кампаний, групп объявлений и объявлений

• Создание мультиформатной рекламы (видео + статичное изображение, различные размеры)

• Загрузка и получение изображений

• Дублирование кампаний и групп объявлений

• Аналитика и сводная аналитика по нескольким аккаунтам

• Диагностика пикселей и отслеживания (5 инструментов)

• Поддержка каталогов и DPA (6 инструментов, включая создание/обновление наборов товаров)

• Полный набор инструментов для таргетинга (6 инструментов)

• Проверка готовности к запуску (более 42 проверок с инструкциями по исправлению)

• Конвейер валидации, принудительное именование, проверка после записи

• Уровни безопасности, ограничение частоты запросов, ссылки на откат

• 215 автоматизированных тестов

Премиум-пакет — добавляет 41 инструмент:

• Движок оптимизации (очереди на проверку, обучение, эксперименты, контроль бюджета, ротация креативов)

• Интеллектуальное хранилище и генерация текстов (голос бренда, таргетинг на ICP, выбор концепций)

• Контроль качества греческого языка (обнаружение греклиша, проверка орфографии)

• Набор автоматизации (диагностика, массовые операции, аудит аккаунта)

• Загрузка хранилища (15 файлов шаблонов на клиента)

• Премиум-тесты и оценки

Премиум-пакет доступен отдельно. Публичные инструменты полностью работают без него.

В чем отличия

• Проверено в продакшене на 37+ клиентских кампаниях с реальными бюджетами и сложными кейсами

• Не является оберткой — включает движок оптимизации, системы безопасности, валидаторы и откат

• Интеграция с хранилищем — считывает данные о клиенте (ICP, голос бренда, подходы) для создания более эффективной рекламы

• Встроенный контроль качества греческого языка (адаптируется под валидацию любого языка)

• Вся реклама создается в статусе PAUSED — ничего не запускается без явного одобрения оператора

• Под надзором, а не автономно — оператор подтверждает каждую запись, активацию и изменение бюджета

Классификация инструментов

Архитектура

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)

Категории инструментов

Функции движка

• Циклы оптимизации — автоматическое перераспределение бюджета на основе сигналов эффективности

• Управление экспериментами — отслеживание A/B тестов со статистической значимостью

• Контроль бюджета — предотвращение перерасхода с настраиваемыми дневными/общими лимитами

• Ротация креативов — обнаружение усталости и автоматические триггеры обновления креативов

• Обучение политик — отслеживание результатов действий и адаптация уверенности со временем

• Шлюз именования — жесткое соблюдение соглашений об именовании перед любой записью в API

Функции безопасности

• Ограничение частоты запросов — соблюдение лимитов Meta API с задержками

• Откат — отмена недавних изменений с журналом выполнения

• Проверка дубликатов — предотвращает случайное создание дубликатов кампаний/объявлений

• Блокировка файлов — безопасный параллельный доступ к хранилищу

• Уровневый доступ — уровни безопасности для каждого аккаунта (песочница, стандарт, продакшен)

Набор валидаторов

• Валидатор соответствия — предварительная проверка политики рекламы Meta

• Валидатор спецификаций креативов — проверка размеров и форматов изображений/видео

• Валидатор отслеживания — проверка пикселя и событий перед запуском

• Валидатор структуры — проверка согласованности структуры кампании

• Операционный валидатор — проверка бюджета, расписания и таргетинга

Неиспользуемый код

Код, который присутствует в репозитории, но НЕ является частью активной поверхности инструментов:

• reporting/templates.py, reporting/formatter.py — не импортируются во время выполнения, активная генерация отчетов отсутствует

• evals/ — внутренние заглушки для оценки, не предназначены для оператора

• Внутренние помощники (не инструменты MCP): identity.py (разрешение IG), api.py (HTTP-клиент), auth.py (проверка токена), utils.py (помощники форматирования), safety/ (ограничитель частоты, откат, дедупликация), validators/ (конвейер валидации перед записью)

Установка

1. Установка

cd meta-ads-mcp
uv sync

2. Переменные окружения

Скопируйте .env.example в .env и заполните свои значения:

cp .env.example .env

Обязательно:

• META_ACCESS_TOKEN — токен доступа к Meta Marketing API (рекомендуется токен системного пользователя)

Опционально:

• META_APP_SECRET — для appsecret_proof (рекомендуется для продакшена)

• META_APP_ID — ID приложения Meta

• VAULT_PATH — путь к вашей директории маркетингового хранилища (по умолчанию ~/marketing-vault)

3. Конфигурация MCP

Добавьте в конфигурацию Claude Code MCP (.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. Структура хранилища (опционально)

Если используется интеграция с хранилищем для данных о клиенте:

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

Тестирование

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

Лицензия

MIT — см. LICENSE.