Skip to main content
Glama
adpilot-mcp

adpilot-mcp

Official
by sholaxai

adpilot-mcp

ci

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?

list_campaigns

Every campaign across connected platforms

no

campaign_performance

Spend, CTR, CPC, CPA, ROAS, CPM over N days, ranked by ROAS

no

detect_anomalies

Robust z-score (median + MAD) anomaly detection on spend, CPA, ROAS, CTR, CPC

no

propose_budget_plan

Builds a reallocation plan and returns a short-lived planId

no

apply_budget_plan

Executes a plan once, before it expires

yes

set_campaign_status

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.

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

  2. Score = shrunkROAS ^ aggressiveness.

  3. 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 ±maxStep of its current budget.

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

Add 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 config

Adding 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 typecheck

Roadmap

  • Google Ads adapter (GAQL searchStream)

  • OpenAI Ads adapter

  • Hourly pacing alerts

  • Creative-level fatigue detection

License

MIT

Available Tools

6 tools
apply_budget_planA
Destructive

Execute a previously proposed budget plan. Plans expire and can only be applied once.

Inputs: planId (required).

campaign_performanceA
Read-only

KPIs (spend, CTR, CPC, CPA, ROAS, CPM) per campaign over the last N days, ranked by ROAS.

Inputs: days.

detect_anomaliesB
Read-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_campaignsB
Read-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_statusA
Destructive

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

    A3.7/5.0

    Scored across 6 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    Six tools is well-scoped for a focused ad budget optimization server. Each tool supports a distinct step in the workflow without obvious filler.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables reading and mutating Google Ads campaigns via MCP tools, and includes structured marketer workflows for search term mining, budget optimization, and weekly reviews.
      6
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables 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.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to query campaign performance, metrics, audiences, and geography, and to analyze budgets, wasted spend, and account health through natural language.
      1
      MIT