AdLoop

Stop switching between Google Ads, GA4, and your code editor to figure out why conversions dropped.

An MCP server that gives your AI assistant read + write access to Google Ads and GA4 — with safety guardrails that prevent accidental spend.

pip install adloop

</div>

What It Solves

AdLoop exists because managing Google Ads alongside your code is a mess. These are the specific problems it handles:

"My conversions dropped and I don't know why." AdLoop cross-references Ads clicks, GA4 sessions, and conversion events in one query. It detects whether the gap is from GDPR consent rejection, broken tracking, or an actual landing page problem — before you waste hours checking each dashboard separately.
"I'm wasting ad spend on irrelevant searches." Pull your search terms report, identify the junk, and add negative keywords — all from a single conversation in your IDE. No context-switching to the Ads UI.
"Is my tracking even working?" Compare the event names in your actual codebase against what GA4 is receiving. Find the mismatches: events you fire that GA4 never sees, events GA4 records that you didn't know about.
"I need to create ads but the Google Ads UI is hostile." Draft responsive search ads, create campaigns, add keywords — all through natural language. Every change shows a preview first. Nothing goes live without your explicit confirmation. New ads and campaigns start paused.
"My landing page gets paid traffic but nobody converts." AdLoop joins your ad final URLs with GA4 page-level data. See which pages get clicks but no conversions, which have high bounce rates, and which ones are orphaned from any ad campaign.
"I don't know if my EU consent setup is causing data gaps." In Europe, 30-70% of users reject analytics cookies. AdLoop accounts for this automatically — it won't diagnose a normal GDPR consent gap as broken tracking.

Built From Real Usage

Every tool exists because of an actual problem hit while running real Google Ads campaigns. The cross-reference tools exist because we kept manually asking the AI to "get Ads data, then get GA4 data, then compare them" — so we automated the join. The Broad Match + Manual CPC safety rule exists because the AI once created that exact combination and wasted budget. The GDPR consent awareness exists because the AI kept diagnosing normal EU cookie rejection as broken tracking.

The best features come from real workflows. If you're using AdLoop and find yourself wishing it could do something it can't, open an issue describing your situation — not just "add feature X" but "I was trying to do Y and couldn't because Z." The context matters more than the request.

All 26 Tools

Quick start: pip install adloop or git clone https://github.com/kLOsk/adloop.git && cd adloop && uv sync && uv run adloop init

Diagnostics

| Tool | What It Does | |------|-------------| | health_check | Test OAuth, GA4, and Ads connectivity in one call — actionable error messages if anything is broken. Also reports the pinned Google Ads API version and warns if a newer version is available. |

GA4 Read Tools

| Tool | What It Does | |------|-------------| | get_account_summaries | List GA4 accounts and properties | | run_ga4_report | Custom reports — sessions, users, conversions, page performance | | run_realtime_report | Live data — verify tracking fires after deploys | | get_tracking_events | All configured events and their volume |

Google Ads Read Tools

| Tool | What It Does | |------|-------------| | list_accounts | Discover accessible Ads accounts | | get_campaign_performance | Campaign metrics — impressions, clicks, cost, conversions, CPA | | get_ad_performance | Ad copy analysis — headlines, descriptions, CTR | | get_keyword_performance | Keywords — quality scores, competitive metrics | | get_search_terms | What users actually searched before clicking | | get_negative_keywords | List existing negative keywords for a campaign or all campaigns | | run_gaql | Arbitrary GAQL queries for anything else |

Cross-Reference Tools (GA4 + Ads Combined)

These tools call both APIs internally and return unified results with auto-generated insights. They're the core of what makes AdLoop different from having separate GA4 and Ads tools.

| Tool | What It Does | |------|-------------| | analyze_campaign_conversions | Maps Ads clicks → GA4 sessions → conversions per campaign. Detects GDPR consent gaps, computes real CPA, compares paid vs organic channels. | | landing_page_analysis | Joins ad final URLs with GA4 page data. Shows conversion rate, bounce rate, and engagement per landing page. Flags pages with paid traffic but zero conversions. | | attribution_check | Compares Ads-reported conversions vs GA4 events. Diagnoses whether discrepancies are from GDPR consent, attribution windows, or broken tracking. |

Tracking Tools

| Tool | What It Does | |------|-------------| | validate_tracking | Compare event names found in your codebase against what GA4 actually records. Returns matched, missing, and unexpected events with diagnostics. | | generate_tracking_code | Generate ready-to-paste GA4 gtag JavaScript for any event, with recommended parameters for well-known events (sign_up, purchase, etc.) and optional trigger wrappers. |

Planning Tools

| Tool | What It Does | |------|-------------| | estimate_budget | Forecast clicks, impressions, and cost for a set of keywords using Google Ads Keyword Planner. Supports geo/language targeting. Essential for budget planning before launching campaigns. |

Google Ads Write Tools

All write operations follow a draft → preview → confirm workflow. Nothing executes without explicit approval.

| Tool | What It Does | |------|-------------| | draft_campaign | Create a full campaign structure — budget + campaign (PAUSED) + ad group + optional keywords. Validates bidding strategy, enforces budget caps, rejects unsafe BROAD match + Manual CPC combinations. | | draft_responsive_search_ad | Create RSA preview (3-15 headlines ≤30 chars, 2-4 descriptions ≤90 chars). Warns if headline/description count is below best practice. | | draft_keywords | Propose keyword additions with match types. Proactively checks bidding strategy — blocks BROAD match on Manual CPC campaigns. | | add_negative_keywords | Propose negative keywords to reduce wasted spend | | pause_entity | Pause a campaign, ad group, ad, or keyword | | enable_entity | Re-enable a paused entity | | remove_entity | Permanently remove an entity (irreversible — prefers pause). Supports keywords, negative keywords, ads, ad groups, campaigns. | | confirm_and_apply | Execute a previously previewed change |

Orchestration Rules

AdLoop ships with orchestration rules that teach the AI how to combine these tools — marketing workflows, GAQL syntax, safety protocols, GDPR awareness, and best practices. Without rules, the AI has tools but doesn't know the playbook.

Cursor: .cursor/rules/adloop.mdc (canonical source)
Claude Code: .claude/rules/adloop.md (synced from Cursor rules via scripts/sync-rules.py)

The rules include:

Orchestration patterns for common workflows (performance review, conversion diagnosis, campaign creation, negative keyword hygiene, tracking validation, budget planning, landing page analysis)
GAQL quick reference with syntax, common queries, and gotchas
Safety rules including Broad Match + Manual CPC prevention and pre-write validation
Ad copy character limit guidance (30-char headlines are shorter than you think)
GDPR consent awareness to prevent false tracking diagnoses in EU markets

Slash Commands (Claude Code)

AdLoop includes pre-built slash commands in .claude/commands/ for common workflows:

| Command | What It Does | |---------|-------------| | /analyze-performance | Full performance review across Google Ads + GA4 | | /create-ad | Create a responsive search ad with safety checks | | /diagnose-tracking | Diagnose tracking and conversion issues | | /optimize-campaign | Full optimization checklist for a campaign | | /create-campaign | Create a new search campaign with budget estimation | | /budget-plan | Estimate budget for keywords via Keyword Planner |

Safety Model

AdLoop manages real ad spend, so safety is not optional.

Two-step writes. Every mutation returns a preview first. A separate confirm_and_apply call is required to execute.
Dry-run by default. Even confirm_and_apply defaults to dry_run=true. Real changes require explicit dry_run=false.
Budget caps. Configurable maximum daily budget — the server rejects anything above the cap.
Audit log. Every operation (including dry runs) is logged to ~/.adloop/audit.log.
New campaigns and ads are PAUSED. Nothing goes live without manual enablement.
Destructive ops require double confirmation. Removing entities or large budget increases trigger extra warnings.
**Broad Match + Manual CPC

Adloop

Install / Use

README