[!TIP] AdLoop Cloud is the hosted version of this project, live now and free during beta. Connect Google in two clicks and use the full toolset from claude.ai, ChatGPT, Claude Code, Cursor, or Gemini. No Google Cloud project, no developer token, no OAuth verification wait. EU-hosted, GDPR-first, DPA included.

📚 Documentation: docs.getadloop.com — setup guides per AI client, toolsets, the safety model, and troubleshooting for both editions.

---

Cloud or Self-Hosted?

Both versions run the same tools with the same safety model. The difference is who handles the plumbing:

	☁️ AdLoop Cloud	🛠️ Self-hosted (this repo)
Setup	Connect Google in two clicks	~5 min: own Google Cloud project + adloop init
Google Cloud project	Not needed	Required (free)
Ads developer token	Not needed	Required (from your MCC)
Works with	claude.ai, ChatGPT, Claude Code, Cursor, Gemini	Claude Code, Cursor, Claude Desktop, any local MCP client
Where your data flows	EU servers (Germany), GDPR-first, DPA included	100% your machine — nothing leaves it
Updates	Automatic	pip install -U adloop
Price	Free during beta	Free forever (MIT)

Not sure? Start with Cloud — it's the fastest way to see what AdLoop can do, and it's the only way to use AdLoop from claude.ai or ChatGPT. Self-host when you want everything on your own machine or need to modify the code. And if you're here to hack on AdLoop itself: welcome, keep scrolling.

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.

• "Are conversions even being tagged on every page?" AdLoop reads your live Google Tag Manager container, joins it against the events in your codebase and the events firing in GA4, and tells you exactly which conversions are being captured, which tags are paused, which page-scope filters are too narrow, and which codebase events have no tag at all — the kind of three-way audit GTM Preview can't give you in a single view.

• "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 Tools

Quick start: pip install adloop or git clone https://github.com/kLOsk/adloop.git && cd adloop && uv sync && uv run adloop init — or zero setup on AdLoop Cloud

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 direct campaign-level negative keywords
get_negative_keyword_lists	List all shared negative keyword lists (SharedSets) — names, IDs, status, keyword count
get_negative_keyword_list_keywords	List the keywords inside a specific shared negative keyword list
get_negative_keyword_list_campaigns	List which campaigns a shared negative keyword list is attached to
get_recommendations	Google's auto-generated recommendations with type, estimated impact, and campaign context
get_pmax_performance	Performance Max campaign metrics with network breakdown + asset group ad strength
get_asset_performance	Per-asset details for PMax — field type, serving status, content
get_detailed_asset_performance	Top-performing asset combinations — which headline+description+image combos Google selects most
get_audience_performance	Audience segment performance — remarketing, in-market, affinity, demographics
get_demographic_targeting	List demographic criteria (age/gender/parental status/income) on an ad group or campaign
run_gaql	Arbitrary GAQL queries for anything else

Compact mode — get_campaign_performance, get_keyword_performance, get_search_terms, and get_ad_performance accept compact=true: account totals, breakdowns, top-10 rows, and pre-computed offender lists (zero-conversion spenders, low-QS keywords, negative-keyword candidates, thin RSAs) instead of every row. ~90% smaller responses — built for account audits so raw tables don't flood your AI's context.

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.

Google Tag Manager Tools