KonQuest Meta Ads MCP

Supervised Meta Ads Operating System for Claude Code.

pip install konquest-meta-ads-mcp

Open-Core Model

KonQuest Meta Ads MCP uses an open-core model.

Public package, this repository, 57 tools, MIT license

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

Premium bundle, adds 41 tools

• Advisory optimization engine, review queues, learning, experiments, budget governor, creative rotation
• Vault intelligence and copy generation, including 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

Get the Premium Bundle (€149 launch price)
One-time purchase, perpetual license. Public tools work fully without it.

Quick Start

1. Install

pip install konquest-meta-ads-mcp

2. Copy environment template

cp .env.example .env

3. Set your token

Required:

• META_ACCESS_TOKEN

Optional:

• META_APP_SECRET
• META_APP_ID
• VAULT_PATH

4. Add it to Claude Code

Add this to your .mcp.json:

{
  "mcpServers": {
    "meta-ads": {
      "command": "uv",
      "args": ["--directory", "/path/to/konquest-meta-ads-mcp", "run", "python", "-m", "meta_ads_mcp"],
      "env": {
        "META_ACCESS_TOKEN": "your_token_here",
        "VAULT_PATH": "/path/to/your/marketing-vault"
      }
    }
  }
}

5. Run setup validation

Use run_setup_check first to validate token, permissions, accounts, pages, IG, pixels, and vault readiness.

What Makes This Different

• Production-tested across real client campaigns, real budgets, and real edge cases
• Not a thin wrapper around a handful of Meta API calls
• Safety-first by design, with validation, naming gates, diagnostics, verification, and rollback
• Multi-asset workflows included, for both video and static image variants
• Supervised, not autonomous, the operator confirms every meaningful write
• Vault-aware architecture, premium workflows can read client intelligence such as ICPs, brand voice, and messaging angles
• Greek language QA built in, adaptable to broader language validation workflows
• Ads created paused by default, nothing goes live without explicit operator intent

Public Package Capabilities

The public repository contains the execution and control layer.

Account management

• Token health
• Ad account discovery
• Pages
• Instagram identities
• Discovery workflows

Campaigns

• Create
• Read
• Update
• Structural delete workflows

Ad sets

• Create
• Read
• Update
• Standalone duplication

Ads

• Create
• Read
• Update
• Creative swap workflows

Creative workflows

• Standalone single-image creative creation
• Creative name update
• Multi-asset video workflows
• Multi-asset static image workflows

Images and video

• Image upload from URL
• Image retrieval by hash
• Video upload
• Video processing status

Insights and diagnostics

• Single-account insights
• Bulk cross-account insights
• Pixel diagnostics
• Tracking checks
• Catalog and DPA diagnostics

Catalog and DPA

• Catalog reads
• Feed visibility
• Product set create
• Product set update

Targeting

• Interests
• Behaviors
• Geo
• Demographics
• Suggestions
• Audience size estimation

Setup and control

• Setup readiness checker
• Validation pipeline
• Naming enforcement
• Post-write verification
• Safety tiers
• Rate limiting
• Rollback references

Premium Bundle Capabilities

The premium bundle adds the intelligence and optimization layer.

Advisory Optimization Engine

• Optimization cycles
• Review queues
• Outcome evaluation
• Learning cycles
• Experiment planning and evaluation
• Budget governor
• Creative rotation
• Operator digests

Vault Intelligence and Copy Generation

• Vault-driven copy generation
• Copy validation
• Brand voice grounding
• ICP-aware messaging
• Concept selection

Automation Suite

• Greek language QA
• Full account diagnostics
• Bulk ad copy fixes
• Product extension workflows
• Multi-account audit

Vault Bootstrap

• Creates 15 canonical template files per client
• Speeds up onboarding for premium intelligence workflows

Tool Availability Summary

Public package

Premium bundle

Full System Classification

This classification refers to the full KonQuest system, meaning public package plus premium bundle.

Architecture

Public package architecture

meta_ads_mcp/
  core/          # Public API read/write modules
  safety/        # Rate limiting, rollback, tiers, duplicate checks
  validators/    # Compliance, creative, tracking, structure, operational validation
  engine/        # Public helper modules required by the open-core package

Full platform architecture, public plus premium

meta_ads_mcp/
  core/          # 66 tools across public and premium core workflows
  engine/        # 32 premium advisory and optimization tools
  validators/    # Quality gates
  safety/        # Rate limiting, rollback, duplicate checking, file locks, tier access
  ingestion/     # Internal ingestion and manifest pipeline

Engine Features

• Optimization loops for budget shifting based on performance signals
• Experiment management with evaluation and winner promotion workflows
• Budget governors to reduce overspend risk
• Creative rotation to detect fatigue and stale creative conditions
• Policy learning to track outcomes and adapt confidence over time
• Naming gate to enforce consistent naming before API writes

Safety Features

• Rate limiting with backoff for Meta API usage
• Rollback for recent changes with execution journal support
• Duplicate checking to reduce accidental duplicate campaign and ad creation
• File locks for safer concurrent local state access
• Tier-based access with sandbox, standard, and production-style controls

Validator Suite

• Compliance validator for policy-oriented pre-checks
• Creative spec validator for image and video validation
• Tracking validator for pixel and event verification
• Structure validator for campaign structure consistency
• Operational validator for budget, schedule, and targeting sanity checks

Setup

1. Install

pip install konquest-meta-ads-mcp

Or from source:

git clone https://github.com/brandu-mos/konquest-meta-ads-mcp.git
cd konquest-meta-ads-mcp
uv sync

2. Environment Variables

Copy .env.example to .env and fill in your values:

cp .env.example .env

Required:

• META_ACCESS_TOKEN, Meta Marketing API access token, system user token recommended

Optional:

• 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

3. MCP Configuration

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

{
  "mcpServers": {
    "meta-ads": {
      "command": "uv",
      "args": ["--directory", "/path/to/konquest-meta-ads-mcp", "run", "python", "-m", "meta_ads_mcp"],
      "env": {
        "META_ACCESS_TOKEN": "your_token_here",
        "VAULT_PATH": "/path/to/your/marketing-vault"
      }
    }
  }
}

4. Vault Usage

Vault usage is optional for the public open-core package.

Premium intelligence and copy workflows rely on vault-based client context.

If using vault-backed workflows:

your-vault/
  01_CLIENTS/{client-slug}/
    00-profile.md
    02-icp-personas.md
    04-brand-voice.md
    05-messaging-house.md
    08-objections.md
    matrix.md
  02_COMPETITORS/{slug}/
    landscape.md

Testing

uv run --extra dev python -m pytest tests/ -v

• Public package: 181 passing
• Full system with premium: 246 passing

Premium Bundle

The premium bundle upgrades the public package into the full KonQuest system.

It adds 41 tools for:

• Advisory optimization engine
• Vault intelligence
• Copy generation
• Greek language QA
• Automation workflows
• Vault bootstrap
• Premium tests and evaluations

Get the Premium Bundle (€149 launch price)

Commercial model

• One-time purchase
• Perpetual license for the purchased version
• No subscription
• No redistribution or resale

Who This Is For

KonQuest is a fit for:

• Meta Ads operators
• Agencies
• Solo performance marketers
• Technical marketers working in Claude Code
• Builders who want a supervised Meta Ads operating layer

Who This Is Not For

KonQuest is not a fit for:

• People who want a hosted SaaS dashboard
• Users looking for autonomous ad buying
• Buyers who want a no-setup web app
• People who do not work with Meta Ads operations

License

MIT, see LICENSE.