KonQuest Meta Ads MCP

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

- 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.

- Production-testedacross 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 QAbuilt 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

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)

- Optimization loops- automated budget shifting based on performance signals
- Experiment management- A/B test tracking with statistical significance
- Budget governors- prevent overspend with configurable daily/lifetime limits
- Creative rotation- fatigue detection and automatic creative refresh triggers
- Policy learning- tracks action outcomes and adapts confidence over time
- Naming gate- hard enforcement of naming conventions before any API write

- Rate limiting- respects Meta API rate limits with backoff
- Rollback- undo recent changes with execution journal
- Duplicate checking- prevents accidental duplicate campaigns/ads
- File locks- safe concurrent access to vault storage
- Tier-based access- safety tiers per account (sandbox, standard, production)

- Compliance validator- Meta ad policy pre-check
- Creative spec validator- image/video dimension and format validation
- Tracking validator- pixel and event verification before launch
- Structure validator- campaign structure consistency checks
- Operational validator- budget, schedule, and targeting sanity checks

Code that exists in the repository but is NOT part of the active tool surface:

- reporting/templates.py, reporting/formatter.py- not imported at runtime, no active report generation
- evals/- internal evaluation stubs, not operator-facing
- Internal helpers(not MCP tools): identity.py (IG resolution), api.py (HTTP client), auth.py (token verification), utils.py (format helpers), safety/ (rate limiter, rollback, dedup), validators/ (pre-write validation pipeline)

Copy.env.exampleto.envand fill in your values:

- META_ACCESS_TOKEN- Meta Marketing API access token (system user token recommended)

- META_APP_SECRET- for appsecret_proof (recommended for production)
- META_APP_ID- Meta app ID
- VAULT_PATH- path to your marketing vault directory (defaults to~/marketing-vault)

Add to your Claude Code MCP config (.mcp.json):