AdLoop MCP server

AdLoop

The Google Ads MCP server for Claude, ChatGPT and Cursor.

Plus Reddit Ads, GA4 and your tracking code, with a preview before every change.

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

☁️ Skip the setup — use AdLoop Cloud (free plan, no card)  ·  or self-host: pip install adloop

[!TIP] AdLoop Cloud is the hosted version of this project, with a free plan that needs no credit card. Connect Google in two clicks and use the full toolset from claude.ai, ChatGPT, Claude Code, Cursor, or Gemini. No Google Cloud project, no API access application, 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 API access	Not needed	Granted to your Cloud project (no developer token, no MCC since Sept 2026)
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 plan, no card; paid plans for more accounts and volume	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: in Claude, ChatGPT and VS Code the preview is an approval card, and only your click on Apply changes the account (the AI cannot press it). 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, key events, page performance. Optional dimension and metric filters, ordering, paging, and a comparison period
run_realtime_report	Live data — verify tracking fires after deploys
get_tracking_events	All configured events and their volume
list_key_events	The property's key events (conversions) with counting method, create time and whether they can be deleted
list_ga4_dimensions_and_metrics	Every dimension and metric the property can report on, including custom ones, with search

Google Ads Read Tools

Tool	What It Does
list_accounts	Discover accessible Ads accounts
get_campaign_performance	Campaign metrics: impressions, clicks, cost, conversions, CPA, Search impression share and share lost to budget/rank
get_ad_performance	Ad copy analysis: headlines, descriptions, CTR, policy approval status and topics
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_recommendation_subscriptions	Which recommendation types Google applies automatically (auto-apply), with status and last change; flags any that are on
get_pmax_performance	Performance Max campaign metrics with network breakdown + asset group ad strength
get_pmax_assets	Per-asset details for PMax — field type, serving status, content
get_asset_group_signals	A PMax asset group's search themes and audience signal, plus the audiences available for it
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_shopping_product_performance	Spend, conversions, CPA and ROAS per product across Shopping and Performance Max, plus products that spent without converting
get_change_history	What changed before the drop: who changed what and when, through which client (UI, API, scripts, auto-applied recommendations), last 30 days
get_demographic_targeting	List demographic criteria (age/gender/parental status/income) on an ad group or campaign
get_audience_lists	The account's remarketing and customer lists (size, eligibility, open/closed), custom and combined segments
search_audience_segments	Find Google's in-market and affinity segments by name
get_audience_targeting	Audiences and audience exclusions on a campaign or ad group, plus the audience mode (observation or targeting)
suggest_brands	Resolve a brand name to the brands Google recognizes — brand ID, name, state, URLs
check_brand_names	Check a shortlist of brand names against Google's brand knowledge graph (max 25 per call)
get_brand_lists	List brand lists (SharedSets of type BRANDS) — ID, name, status, member count
get_brand_list_brands	List the brands inside a list, with the Commercial KG MID and the criterion ID for removals
get_brand_list_campaigns	Which campaigns a brand list is attached to, and whether each attachment excludes or targets
get_ai_max_settings	AI Max knobs per campaign and ad group — enable_ai_max, bundling_required, the full asset_automation_settings list and each ad group's disable_search_term_matching
get_campaign_settings	One flat record per Search campaign — networks, location option, campaign-level broad match, bidding, budget, URL options and AI Max — with the settings that widen reach flagged
get_custom_conversion_goals	Custom conversion goals with their actions, plus one campaign's goal config
run_gaql	Arbitrary GAQL queries for anything else

Brand lists — a list is a SharedSet of type BRANDS; attaching it to a campaign is a CampaignCriterion.brand_list (negative=true excludes, false restricts), not a CampaignSharedSet like negative keyword lists. remove_from_brand_list and detach_brand_list_from_campaigns remove for real — SharedCriterion has no status field.

Brand targeting — brand criteria (brand lists, brand exclusions) target a brand's Commercial Knowledge Graph ID, not its display name. Use suggest_brands for a single name or check_brand_names for a shortlist to get the ID; exact_match marks a candidate whose name matches apart from case and punctuation, everything else is a Google suggestion.

AI Max is the container for Search brand exclusions — Google rejects a brand list on a plain Search campaign with "For search advertising channel, brand lists can only be applied to exclusive targeting, broad match campaigns for inclusive targeting or PMax generated campaigns." draft_prepare_brand_exclusions sets the state that makes the exclusion usable without handing Google the automations: AI Max on, search term matching off per ad group, text and final-URL automation opted out. draft_ai_max_settings is the general form when only parts of that state should change — it refuses a plan that would leave an automation on unnoticed, and asks for a second confirmation when that automation was requested explicitly.

Custom conversion goals — a named set of conversion actions that a campaign can be pointed at. get_custom_conversion_goals shows the goals with their actions and a campaign's current goal config; draft_custom_conversion_goal creates a set, draft_update_custom_conversion_goal renames or replaces its actions, draft_assign_custom_conversion_goal points a campaign at it and draft_clear_custom_conversion_goal puts the campaign back on the account-level goals. Only the goal and the campaign's goal config are touched — conversion actions, bidding and budgets stay as they are.

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

These tools read the live GTM container and join it with the codebase + GA4 to find tracking gaps that pure GA4 inspection can't catch — page-scoped triggers, paused tags, dynamic event names, brittle CSS selectors, and codebase events with no tag wired up at all.

Tool	What It Does
audit_event_coverage	The flagship. Three-way join: codebase events ↔ GTM tags ↔ GA4 actual fires. For each event name in expected_events, returns one of 10 statuses (ok, no_tag_no_fire, tag_paused, tag_active_but_not_firing, gtm_only_firing, ga4_only, etc.) plus auto-generated insights for the gaps.
list_gtm_accounts	Discover accessible GTM accounts
list_gtm_containers	List containers under an account — returns numeric container_id (needed by other tools), public GTM-XXXXXXX ID, and usage context (web/iOS/Android/server)
list_gtm_tags	Every tag in the live container with parsed event names and resolved firing/blocking trigger names. Pass workspace_id to read a workspace's unpublished state instead, so a just-drafted tag is visible (also on get_gtm_tag, list_gtm_triggers, get_gtm_trigger, list_gtm_variables)
get_gtm_tag	Full raw config for a single tag — every parameter, firing/blocking triggers with filter conditions, priority, pause status, sampling
list_gtm_triggers	Every trigger with filter conditions parsed to readable text (e.g. {{Page Path}} contains service-promotions, {{Form ID}} NOT contains wf-form-...). Renders the negate flag explicitly.
get_gtm_trigger	Full trigger config + reverse lookup of every tag that uses it. Includes parsed element_visibility block (selector, on-screen ratio, firing frequency) for elementVisibility triggers and group_member_trigger_ids for triggerGroup types
list_gtm_variables	Custom variables (data layer, constants, JS) plus enabled built-in variables
list_gtm_workspaces	List drafts (workspaces) under a container — workspace IDs are needed by get_gtm_workspace_diff
get_gtm_workspace_diff	Drafted-but-not-published changes — common cause of "I edited a tag but nothing happened". Returns is_clean: true when nothing is pending.
list_gtm_versions	Version history, newest first, with version IDs and entity counts. The Tag Manager API returns no timestamps or author for versions.
get_gtm_version	Name, notes and tag/trigger names for a single historical container version
get_gtm_version_diff	What a publish changed: added, removed and changed tags, triggers and variables with the changed fields, plus built-in variables enabled or disabled. Defaults to the live version against the one before it; two or three API calls.

GTM write tools (opt-in)

Off by default. Set gtm.write_enabled: true in ~/.adloop/config.yaml and restart; the next call asks you to re-consent with the Tag Manager edit + publish scopes, which are never part of the default grant. Everything follows the usual draft → preview → confirm_and_apply flow, and tag/trigger edits only touch a workspace until you publish it.

Tool	What It Does
draft_gtm_tag	Create a tag, or update one by tag_id. Updates are a read-modify-write: parameters merge by key and every field you don't pass (priority, consent settings, firing options, schedule, folder, …) is preserved. Tag types are canonical GTM template IDs (googtag, gaawe, awct, sp, gclidw, …) or cvt_<id> gallery templates.
draft_gtm_trigger	Create a trigger, or update one by trigger_id (type is immutable). custom_event_name wires a customEvent trigger to a dataLayer event.
draft_gtm_variable	Create or update variables, e.g. Data Layer Variables for GA4 ecommerce values; renaming a referenced variable is refused, Custom JavaScript is gated
draft_delete_gtm_entity	Delete a workspace tag, trigger or variable. Triggers and variables still in use are refused up front, with the references listed.
draft_publish_gtm_workspace	Publish a workspace live. The preview lists every pending change, including edits other people made in the GTM UI.
draft_rollback_gtm_version	Republish an older container version live. The preview is the diff from the live version to the target; the plan pins the live version, so apply refuses if someone publishes in between. Workspaces are left as they are.

Safety gates specific to GTM:

• Custom HTML runs arbitrary JavaScript on your site, so creating or editing an html tag — or publishing a workspace that adds or changes one — is refused unless gtm.allow_custom_html: true is also set. Pausing or deleting one is always allowed.
• No stale writes. Updates and deletes pin the entity's fingerprint from the preview, and publish pins the workspace's pending changes; if someone edits the container in between, apply refuses and you re-draft.
• Publishing stops on merge conflicts or GTM compiler errors. The dry run runs a Tag Manager quick preview first (Tag Manager has no validate-only mode), so compiler errors surface before a version is even created. That preview is a POST and stores a preview version in the container — nothing is published and no live tag changes; the rest of the dry run only reads.
• The publish and rollback results name the version they replaced (previous_live_version_id), so rolling back is one step: draft_rollback_gtm_version with that id. If the version was created but publishing it failed, the error carries both the created version id and the still-live one.
• Per-operation names for safety.blocked_operations: gtm_create_tag, gtm_update_tag, gtm_delete_tag, gtm_create_trigger, gtm_update_trigger, gtm_delete_trigger, gtm_publish_workspace, gtm_rollback_version.

The Google account also needs Edit permission on the container (and Publish to publish) under Admin → User Management.

Setup for GTM tools — Enable the Tag Manager API v2 in your GCP project, then add your AdLoop credentials' email (the OAuth user, or the service account email if using a service account) as a Read user on the GTM container under Admin → User Management. Service accounts pick up access on the next call. OAuth users upgrading from an earlier AdLoop version must re-authorize once: the GTM scope is new, so delete ~/.adloop/token.json and run any tool to re-consent — until then GTM tools return a permissions error.

Search Console Tools

Tool	What It Does
list_gsc_sites	List Search Console properties the connected account can access
run_gsc_report	Organic search analytics: clicks, impressions, CTR, position by query/page/country/device/date/searchAppearance/hour. Supports fresh data (data_state="all"), aggregation_type, and paging past 25,000 rows with start_row

Web Performance Tools

Tool	What It Does
analyze_page_speed	PageSpeed Insights for landing pages: Lighthouse score, Core Web Vitals, real-user CrUX data (falls back to origin-wide data, labelled as such, when the page has too little traffic), top fixes. No OAuth needed (optional API key).

Merchant Center Tools

Tool	What It Does
list_merchant_accounts	Discover accessible Merchant Center accounts
get_merchant_feed_health	Feed health — approved/pending/disapproved counts per reporting context, top product issues with docs, account-level issues. Disapprovals silently starve Shopping/PMax.
get_merchant_product_issues	The products behind the feed-health counts: which are disapproved, limited or pending, and each issue with its attribute and affected countries

Setup for Merchant Center tools — Enable the Merchant API in your GCP project (the Content API for Shopping is deprecated). The Merchant API has no read-only scope; AdLoop uses it strictly read-only. Upgrading OAuth users re-authorize once.

Setup for GSC tools — Enable the Search Console API in your GCP project. Upgrading OAuth users must re-authorize once for the new scope (delete ~/.adloop/token.json, run any tool). The killer combo: cross-reference organic queries with get_keyword_performance to find paid/organic cannibalization and untapped keyword opportunities.