I run a marketing agency managing 37+ client ad accounts on Meta. Every day I create campaigns, adjust budgets, fix ad copy, check pixels, rotate creatives. All through the Meta Marketing API.
After months of doing this manually with curl and scripts, I built an MCP server that lets me do everything from Claude Code. Then I open-sourced it.
## What it does
KonQuest Meta Ads MCP gives you 57 tools (free, MIT) for managing Meta Ads directly from Claude Code:
Campaign management - Create, read, update campaigns, ad sets, ads, and creatives. Duplicate campaigns with all their ads in one command.
Multi-asset ads - Create a single ad with video (9:16 + 1:1) and static images (1:1 + 4:5 + 9:16) using asset_feed_spec. No more creating separate ads per format.
Targeting toolkit - Search interests, behaviors, demographics, geo locations. Estimate audience sizes before creating ad sets.
Pixel diagnostics - Check pixel health, verify events are firing, test event sends, diagnose tracking issues on any URL.
Catalog and DPA - Product catalogs, feeds, product sets for dynamic product ads. Create and update product sets with filters.
Setup checker - 42+ automated checks per account: token health, pixel status, page connections, Instagram identity, catalog links.
## How it works in practice
Here's what managing Meta Ads from Claude Code looks like:
▎ Create a conversion campaign for my skincare store
▎ targeting women 25-45 interested in beauty
Claude reads your vault files (brand voice, ICP profiles, angles),
validates everything, enforces naming conventions, checks your
pixel is firing, and creates:
- Campaign (PAUSED)
- Ad set with targeting
- Ads with creatives
Nothing goes live until you say so.
▎ What's the ROAS on campaign C5 this week?
Claude pulls insights, breaks down by ad set,
flags underperformers, suggests budget shifts.
▎ Duplicate campaign C3 but change targeting to men 30-50
Claude duplicates the full structure (campaign + ad sets + ads),
applies new targeting, keeps naming conventions consistent.
## Safety first
Every write operation is supervised:
- All ads created PAUSED - nothing goes live without your explicit approval
- Naming enforcement - every object follows your naming convention before the API call happens
- Validation pipeline - compliance, creative specs, tracking, structure, and operational checks run before every write
- Rate limiting - respects Meta API limits with automatic backoff
- Rollback references - every change is logged so you can undo it
- Safety tiers - sandbox, standard, production access levels per account
## The vault system
The server reads local markdown files (your "vault") for client intelligence:
your-vault/
01_CLIENTS/my-client/
00-profile.md # Account IDs, pixel, page
02-icp-personas.md # Target audience profiles
04-brand-voice.md # Tone, language, style
05-messaging-house.md # Angles, value props
matrix.md # Decision matrix
This means ad copy and targeting suggestions are grounded in actual client data, not generic AI output.
## Installation
bash
pip install konquest-meta-ads-mcp
Add to your .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"
}
}
}
}
Run the setup checker to verify everything works:
> run_setup_check
Open-core model
The 57-tool public package is free and fully functional. You can manage all your Meta Ads campaigns without paying anything.
There's also a premium bundle (41 additional tools, one-time purchase) that adds:
- Optimization engine - automated recommendations for budget shifts, creative rotation, and scaling
- Vault intelligence - generates ad copy grounded in client brand voice and ICP profiles
- Experiment management - A/B test tracking with statistical significance
- Budget governor - prevents overspend with configurable limits
- Greek language QA - Greeklish detection and orthography checks (adaptable to any language)
Premium is completely optional. The free package does the job for most use cases.
Built from production pain
This isn't a weekend project or an API wrapper. It was built from daily production use across 37+ real client accounts with real budgets. Every feature exists because something went wrong
without it:
- Naming enforcement exists because messy account structures made reporting impossible
- The validation pipeline exists because a bad ad set once spent budget on the wrong audience
- Safety tiers exist because a sandbox test accidentally ran on a production account
- Greek QA exists because Greeklish slipped into live ad copy
181 automated tests make sure nothing breaks.
Links
- GitHub: https://github.com/brandu-mos/konquest-meta-ads-mcp
- PyPI: https://pypi.org/project/konquest-meta-ads-mcp/
- Premium bundle: https://farasokster.gumroad.com/l/konquest-meta-ads-mcp-premium
If you manage Meta Ads and use Claude Code, give it a try. Happy to answer questions in the comments.
Top comments (0)