KonQuest Meta Ads MCP

Supervised Meta Ads Operating System for Claude Code.

Open-Core Model

KonQuest Meta Ads MCP uses an open-core model:

Public (this repo) - 57 tools, MIT license:

• Full CRUD for campaigns, ad sets, and ads
• Multi-asset ad creation (video + static image, multi-dimension)
• Image upload and retrieval
• Campaign and ad set duplication
• Insights and bulk cross-account analytics
• Pixel and tracking diagnostics (5 tools)
• Catalog and DPA support (6 tools, including product set create/update)
• Full targeting toolkit (6 tools)
• Setup readiness checker (42+ checks with fix instructions)
• Validation pipeline, naming enforcement, post-write verification
• Safety tiers, rate limiting, rollback references
• 215 automated tests

Premium bundle - adds 41 tools:

• Advisory optimization engine (review queues, learning, experiments, budget governor, creative rotation)
• Vault intelligence and copy generation (brand voice, ICP targeting, concept selection)
• Greek language QA (Greeklish detection, orthography checks)
• Automation suite (diagnostics, bulk operations, account audit)
• Vault bootstrap (15 template files per client)
• Premium tests and evaluations

Premium bundle available separately. Public tools work fully without it.

What Makes This Different

• Production-tested across 37+ client campaigns with real budgets and real edge cases
• Not a wrapper - includes optimization engine, safety gates, validators, and rollback
• Vault-integrated - reads client intelligence (ICPs, brand voice, angles) to generate better ads
• Greek language QA built in (adaptable to any language validation)
• All ads created PAUSED - nothing goes live without explicit operator approval
• Supervised, not autonomous - operator confirms every write, every activation, every budget change

Tool Classification

| Classification | Count | Description | |----------------|:---:|-------------| | production-safe | 38 | Read-only data access. No API writes, no local state changes. | | supervised-only | 29 | Write/delete operations requiring operator approval before execution. | | advisory-only | 31 | Generate recommendations, plans, copy, diagnostics. No Meta API writes. May write local files. | | Total: 98 registered | |

Architecture

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)

Tool Categories

| Category | Tools | Description | |----------|:---:|-------------| | Account Management | 6 | Token health, ad accounts, pages, IG identity, discovery | | Campaigns | 4 | Create, read, update campaigns | | Ad Sets | 4 | Create, read, update ad sets with targeting | | Ads | 4 | Create, read, update ads | | Creatives | 3 | Create, read ad creatives | | Insights & Analytics | 1 | Performance data with archetype-aware normalization | | Pixels & Tracking | 5 | Pixel health, event diagnostics, test events, CAPI | | Catalogs & DPA | 6 | Product catalogs, feeds, product sets, validation | | Audiences | 1 | Custom audience listing | | Targeting | 3 | Interest, behavior, and geo search | | Video Management | 3 | Upload (simple + resumable) and processing status | | Ad Builder | 1 | Multi-asset ad creation with IG gate enforcement | | Copy Engine | 2 | Vault-driven ad copy generation and validation | | Naming Convention | 1 | Enforced naming schema for all objects | | Automation & Diagnostics | 6 | Greek QA, full diagnostic, bulk ops, account audit | | Vault & Intelligence | 2 | Client vault reader, concept selection | | Optimization Engine | 4 | Optimization cycles, launch planning, execution packs | | Mu

... View full README on GitHub