KonQuest Meta Ads MCP MCP Server
io.github.brandu-mos/konquest-meta-ads-mcp
Supervised Meta Ads operating system for Claude with 57 campaign management tools and safety gates.
What this kind of tool is for
- Chain multi-step workflows across the other tools in this directory.
- Run a scheduled or triggered job instead of retyping the same request.
- Have your agent watch a feed, queue, or repo and act on new items.
How to compare servers like this
- Trigger model:
- Understand what starts the automation — a command, a schedule, or an event — before relying on it.
- Blast radius:
- Prefer tools that hand you a review point before an irreversible action runs.
- Chaining cost:
- Each chained step adds a failure point; keep critical paths on the fewest tools.
- Maintenance signal:
- Automations break quietly; a maintained tool is the difference between repair and rediscovery.
This page carries your copy-paste config: pick your MCP client in the install section on this page and use the copy button.
What is the KonQuest Meta Ads MCP MCP server?
The KonQuest Meta Ads MCP is a production-tested Meta Ads management system for Claude Code that provides 57 open-source tools for campaign, ad set, and ad operations with built-in safety gates, validation, and rollback capabilities. It uses a supervised model where all writes require operator approval before execution, and integrates with a marketing vault for client intelligence and copy generation.
KonQuest Meta Ads MCP gives you programmatic control over Meta ad accounts through Claude, with full CRUD operations on campaigns, ad sets, and ads. It includes multi-asset ad creation, bulk analytics, pixel diagnostics, catalog/DPA support, targeting tools, and an optimization engine. All ads are created paused and require explicit approval before going live, making it suitable for production use across multiple client accounts.
How to install KonQuest Meta Ads MCP
Copy-paste configuration for popular MCP clients.
META_ACCESS_TOKENrequiredsecretMeta Marketing API access token
{
"mcpServers": {
"konquest-meta-ads-mcp": {
"command": "uvx",
"args": [
"konquest-meta-ads-mcp"
],
"env": {
"META_ACCESS_TOKEN": "<YOUR_META_ACCESS_TOKEN>"
}
}
}
}Tools & capabilities
Tools this server exposes to the agent.
Campaign Management— Create, read, update campaigns with full CRUD operationsAd Set Management— Create, read, update ad sets with targeting configurationAd Management— Create, read, update ads with multi-asset support (video + static image, multi-dimension)Creative Management— Create and read ad creativesMulti-Asset Ad Creation— Build ads with video and static image combinations across multiple dimensionsImage Upload & Retrieval— Upload and retrieve images for ad creativesCampaign & Ad Set Duplication— Duplicate existing campaigns and ad setsInsights & Analytics— Performance data with archetype-aware normalization and bulk cross-account analyticsPixel & Tracking Diagnostics— Pixel health checks, event diagnostics, test events, and CAPI validation (5 tools)Catalog & DPA Support— Product catalogs, feeds, product sets, and validation (6 tools including product set create/update)Targeting Toolkit— Interest, behavior, and geo search targeting (6 tools)Setup Readiness Checker— 42+ automated checks with fix instructions for account configurationValidation Pipeline— Compliance, creative spec, tracking, structure, and operational validatorsNaming Convention Enforcement— Enforced naming schema for all objectsVideo Management— Simple and resumable video upload with processing status trackingCopy Generation— Vault-driven ad copy generation with brand voice integrationOptimization Engine— Optimization cycles, launch planning, and execution packsBudget & Targeting Mutation— Budget and targeting changes with verificationActivation & Rollback— Status changes and undo operations with preflight checksReview Queue— Operator review queue with outcome snapshots and digests
Use cases
- Programmatically create and manage Meta ad campaigns across multiple accounts with Claude as your operator
- Generate multi-asset ads with automatic validation and approval workflows before going live
- Analyze campaign performance across accounts and get optimization recommendations with budget governors
- Diagnose pixel and tracking issues with automated health checks and CAPI validation
- Build A/B tests with statistical significance tracking and automatic creative rotation based on fatigue detection
KonQuest Meta Ads MCP MCP server FAQ
It's a production-tested Meta Ads management system with 57 open-source tools for campaign operations, built into Claude Code. All writes require operator approval before execution, and it includes safety gates, validation, and rollback capabilities.
Yes, the public version with 57 tools is MIT-licensed and free. A premium bundle with 41 additional tools (optimization engine, vault intelligence, automation suite) is available separately.
Install via pip (konquest-meta-ads-mcp), set up environment variables (META_ACCESS_TOKEN, VAULT_PATH), and add the MCP configuration to your .mcp.json file with the uv command.
You need a Meta Marketing API access token (system user token recommended). Optionally provide META_APP_SECRET for appsecret_proof in production.
No. All ads are created in paused status and require explicit operator approval before activation. The system is supervised, not autonomous.
Yes, it supports multi-account operations with bulk cross-account analytics, tier-based access controls, and account-specific safety settings.
README (reference)
Source of truth, from the repository.
KonQuest Meta Ads MCP
Supervised Meta Ads Operating System for Claude Code. You can find the premium version here: https://farasokster.gumroad.com/l/konquest-meta-ads-mcp-premium
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 |
| Mutation Corridor | 2 | Budget/targeting changes with verification |
| Activation & Rollback | 4 | Status changes and undo with preflight checks |
| Review Queue | 7 | Operator review queue, outcome snapshots, digests |
| Learning Layer | 5 | Policy memory, outcome evaluation, learning cycles |
| Experiments | 7 | A/B testing, budget governor, creative rotation, scaling |
| Copy Generation | 2 | Auto copy chain, vault-grounded Greek copy |
Engine Features
- 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
Safety Features
- 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)
Validator Suite
- 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
Non-Shipped Code
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)
Setup
1. Install
cd 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 IDVAULT_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/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 Structure (Optional)
If using the vault integration for client intelligence:
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
Testing
uv run --extra dev python -m pytest tests/ -v
# Public package: 215 passed | Full (with premium): 246 passed
License
MIT - see LICENSE.
Related MCP servers
Vealth work board: find real work, claim free with your wallet, prove it. Free onchain anchoring.

agent-device
Mobile app automation and verification for AI coding agents on iOS, Android, TV, and desktop.

Reddit Ads
Reddit Ads API v3: campaigns, ad groups, ads, reports, plus working writes with safety tiers.
Deterministic public-web change observation with evidence-bound commercial interpretation.

Flit Physics
Tiny sphere-physics engine for three.js games: spawn, step, raycast, InstancedMesh-ready positions

