adpilot-mcp
OfficialRoadmap item: a planned Google Ads adapter using GAQL searchStream to fetch campaign performance and manage budgets and status alongside other platforms.
Provides an adapter for the Meta Graph API that lists ad campaigns, pulls daily spend/CTR/CPC/CPA/ROAS metrics, updates daily budgets, and pauses or resumes campaigns in a Meta ad account.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@adpilot-mcp Which campaigns are bleeding money this week? Shift budget to what converts."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
adpilot-mcp
An MCP server that lets Claude, ChatGPT or any MCP client analyse and manage paid ad campaigns, with hard guardrails so the model can never torch your budget.
"Which campaigns are bleeding money this week? Move budget to whatever's actually converting."
It pulls the numbers, spots the anomaly, proposes a bounded reallocation and waits for you to approve it.
Tools
Tool | What it does | Mutates? |
| Every campaign across connected platforms | no |
| Spend, CTR, CPC, CPA, ROAS, CPM over N days, ranked by ROAS | no |
| Robust z-score (median + MAD) anomaly detection on spend, CPA, ROAS, CTR, CPC | no |
| Builds a reallocation plan and returns a short-lived | no |
| Executes a plan once, before it expires | yes |
| Pause or resume a campaign | yes |
Related MCP server: Google Ads MCP Server
How the maths works
Anomaly detection. Each day is compared with a trailing 14-day baseline using (x − median) / (1.4826 · MAD). Unlike mean/stddev, one earlier bad day doesn't inflate the baseline and hide the next one. Findings are labelled harmful based on direction, so CPA up is bad and ROAS up is good.
Budget allocation.
Each campaign's ROAS is shrunk toward the portfolio ROAS, weighted by how much it has actually spent. A campaign that spent £8 and got one lucky sale doesn't win the whole budget.
Score =
shrunkROAS ^ aggressiveness.The total is split proportionally, then water-filled: each pass pins whichever side (over-max or under-min) has the bigger violation and redistributes the rest, so the total is conserved exactly while every campaign stays within ±
maxStepof its current budget.Campaigns with a critical, harmful anomaly are frozen rather than boosted.
Guardrails
Two-phase commit: the model can only propose. Applying needs the
planId, which is single-use and expires (30 minutes by default).Per-campaign change cap (default ±25%) and a total daily spend ceiling.
Protected campaigns can never be changed or paused.
Append-only JSONL audit log of every proposal and execution.
Setup
npm install && npm run buildAdd it to Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"adpilot": {
"command": "node",
"args": ["/path/to/adpilot-mcp/dist/index.js"],
"env": {
"META_AD_ACCOUNT_ID": "1234567890",
"META_ACCESS_TOKEN": "EAAB...",
"ADPILOT_MAX_TOTAL_DAILY": "300",
"ADPILOT_MAX_CHANGE_PCT": "0.2",
"ADPILOT_PROTECTED": "120201234,120205678",
"ADPILOT_AUDIT_LOG": "/path/to/adpilot-audit.jsonl"
}
}
}
}With no platform credentials it starts in mock mode, with four seeded campaigns including one that has a runaway-spend anomaly to catch. That makes it easy to demo and test. Set ADPILOT_MOCK=1 to force mock mode alongside real adapters.
Architecture
src/
adapters/ AdsAdapter interface, registry, Meta Graph API, seeded mock
analytics/ metrics roll-up, robust anomaly detection, ROAS allocator
guardrails/ policy checks, plan lifecycle, audit log
server.ts MCP tool definitions (zod-validated)
index.ts stdio entrypoint + env configAdding a platform means implementing four methods: listCampaigns, getDailyMetrics, setDailyBudget and setStatus.
Tests
npm test # unit tests + full MCP client↔server round-trips over an in-memory transport
npm run typecheckRoadmap
Google Ads adapter (GAQL
searchStream)OpenAI Ads adapter
Hourly pacing alerts
Creative-level fatigue detection
License
MIT
Available Tools
6 toolsapply_budget_planADestructive
Execute a previously proposed budget plan. Plans expire and can only be applied once.
Inputs: planId (required).
campaign_performanceARead-only
KPIs (spend, CTR, CPC, CPA, ROAS, CPM) per campaign over the last N days, ranked by ROAS.
Inputs: days.
detect_anomaliesBRead-only
Flag unusual moves in spend/CPA/ROAS/CTR/CPC using robust z-scores (median + MAD) against a trailing baseline. Returns the most severe first.
Inputs: days, threshold, onlyHarmful.
list_campaignsBRead-only
List every campaign across connected ad platforms with status and daily budget.
Inputs: status.
propose_budget_planA
Propose a reallocation of daily budgets toward higher-ROAS campaigns. Uses spend-weighted ROAS shrinkage and bounded water-filling. Nothing changes until apply_budget_plan is called.
Inputs: days, maxStep, totalDaily, aggressiveness, +1 more.
set_campaign_statusADestructive
Pause or resume a single campaign. Protected campaigns are refused.
Inputs: status (required), campaignId (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a clearly distinct role: listing campaigns, measuring KPIs, detecting anomalies, proposing a plan, applying a plan, and changing status. The propose/apply pair is intentionally split and clearly differentiated by lifecycle stage.
All names use consistent snake_case, and most follow a verb_noun pattern such as list_campaigns, detect_anomalies, propose_budget_plan, and set_campaign_status. campaign_performance is the one minor deviation, using a noun phrase instead of a verb-led name.
Six tools is well-scoped for a focused ad budget optimization server. Each tool supports a distinct step in the workflow without obvious filler.
The surface covers the core workflow: inspect campaigns, measure performance, detect issues, propose and apply budget changes, and pause/resume campaigns. Minor gaps exist around inspecting or cancelling proposed plans and retrieving detailed campaign-level configuration.
Maintenance
Related MCP Connectors
Budget pacing and ad management for Google, Meta, LinkedIn, Microsoft, TikTok, Reddit, Amazon and X
1AI agents that manage paid ads on Meta, LinkedIn, and Google Ads from any MCP client.
Creative-intelligence MCP for campaign strategy, ad builds, QA, and reporting.
Google Ads MCP: reports, search terms, negatives, budgets, campaigns. Approval on every write.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceEnables monitoring and managing multi-platform media buying accounts via natural language, detecting anomalies like creative fatigue and spend spikes, with AI-powered recommendations and a human-in-the-loop approval queue.-
- AlicenseNot gradedqualityDmaintenanceEnables reading and mutating Google Ads campaigns via MCP tools, and includes structured marketer workflows for search term mining, budget optimization, and weekly reviews.6MIT
- FlicenseNot gradedqualityCmaintenanceEnables managing mock Facebook Ads Manager-style campaigns through MCP, including querying nested campaign/ad set/ad performance data, flagging underperformers, drafting budget, creative, and pause/resume proposals, and applying changes only after human review or dashboard approval.-
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to query campaign performance, metrics, audiences, and geography, and to analyze budgets, wasted spend, and account health through natural language.1MIT