AdLoop

The AI command center for Google Ads, GA4, and tracking code.

👁 PyPI
👁 License: MIT
👁 Python 3.11+
👁 MCP Compatible
👁 Google Ads API
👁 GA4 Data API
👁 GitHub stars

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

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.

Related MCP server: agent1st-ads-mcp

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 43 Tools

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

Diagnostics

GA4 Read Tools

Google Ads Read Tools

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.

Tracking Tools

Planning Tools

Google Ads Write Tools

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

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, keyword discovery, 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:

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 blocked. The #1 cause of wasted ad spend is automatically prevented — draft_keywords refuses to add BROAD match keywords to campaigns without Smart Bidding.

• Pre-write validation. Before any write, the AI checks bidding strategy, conversion tracking status, and quality scores. If the campaign is fundamentally broken, AdLoop warns you instead of making things worse.

• Structured error handling. All tools return actionable error messages with hints instead of raw exceptions. Auth errors include specific re-authorization steps.

• API version pinning. The Google Ads API version is pinned to prevent silent breaking changes from library updates. health_check warns when a newer version is available.

• Ask mode compatibility. Read tools declare readOnlyHint so they work in Cursor's Ask mode without switching to Agent mode.

Setup

⚠️ Built-in OAuth credentials are temporarily unavailable while Google verification is pending. Google limits unverified OAuth apps to 100 users, and AdLoop has reached that cap. New users will see a "This app is blocked" error if they pick the built-in option in the wizard.

What this means for you: until Google completes verification, bring your own Google Cloud project — it takes ~5 minutes, has no user cap, and the adloop init wizard guides you through it. Status updates: Discussion #13.

(Existing users whose tokens were already issued before the cap continue to work — only first-time sign-ins are blocked.)

Install

From PyPI:

pip install adloop
adloop init

From source:

git clone https://github.com/kLOsk/adloop.git
cd adloop
uv sync
uv run adloop init

What adloop init does

The wizard defaults to the "bring your own Google Cloud project" path while verification is pending. It walks you through:

1. Google Cloud setup — creates a project, enables the three APIs, generates an OAuth client (see Custom Google Cloud Project Setup below for the exact steps the wizard refers you to)

2. Developer token — from your Google Ads MCC (API Center)

3. MCC Account ID — your Manager Account ID (top bar in the MCC UI)

4. OAuth sign-in — opens a browser to sign in with Google (or prints a URL for headless servers)

5. Auto-discovers your accounts — finds your GA4 properties and Ads accounts automatically

6. Safety defaults — budget cap and dry-run preference

7. Editor config snippets — prints MCP configuration for both Cursor and Claude Code

The wizard does still offer AdLoop's built-in credentials as a non-default option for existing users whose tokens predate the cap. Picking that option for a brand-new Google account will fail at the consent screen — the wizard warns you about this before you choose.

Requirements

• Python 3.11+

• A Google Ads account with an MCC (Manager Account)

• A Google Ads Developer Token (see below)

Google Ads Developer Token

A developer token is always required — even when using AdLoop's built-in OAuth credentials. The built-in credentials handle Google sign-in; the developer token is a separate key that grants API access to your Google Ads data.

1. Create an MCC (free) at ads.google.com/home/tools/manager-accounts if you don't have one. Link your regular Google Ads account to it.

2. In the MCC, go to Tools & Settings → API Center

3. Your developer token is shown there. Copy it — the wizard will ask for it.

Access levels — your token's access level determines what it can do:

Getting DEVELOPER_TOKEN_NOT_APPROVED? Your token is at "Test Account" level. Go to API Center in your MCC and check your access level. If it shows "Test Account", you need to apply for Basic access or wait for Explorer access to be granted after your first production API call.

Headless Servers

Running on a server without a browser (VMs, Docker, SSH)? The wizard automatically detects this and falls back to a manual flow: it prints an authorization URL you can open on any device, then you paste the redirect URL back into the terminal.

Custom Google Cloud Project Setup

This is the default path while built-in credentials are blocked by Google's 100-user cap. The wizard refers to these steps — do them in your browser before running adloop init (or while it waits at the OAuth prompt).

Step 1 — Google Cloud Project

1. Go to console.cloud.google.com and create a new project

2. Enable these three APIs (search for each in the API Library):

   • Google Analytics Data API — for GA4 reports and events

   • Google Analytics Admin API — for listing GA4 properties

   • Google Ads API — for all ads operations

Step 2 — OAuth Credentials

1. In your Google Cloud project, go to APIs & Services → Credentials

2. Click Create Credentials → OAuth client ID

3. Select Desktop app as the application type, give it any name

4. Download the JSON file and save it as ~/.adloop/credentials.json

Service accounts are also supported — just place the service account key JSON at the same credentials_path. AdLoop detects the file type automatically.

Step 3 — Connect to Your Editor

Cursor — Add to your project's .cursor/mcp.json:

{
 "mcpServers": {
 "adloop": {
 "command": "/absolute/path/to/adloop/.venv/bin/python",
 "args": ["-m", "adloop"]
 }
 }
}

Then copy .cursor/rules/adloop.mdc from this repo into your project's .cursor/rules/ directory.

Claude Code — Run:

claude mcp add --transport stdio adloop -- /absolute/path/to/adloop/.venv/bin/python -m adloop

Or add to your project's .mcp.json:

{
 "mcpServers": {
 "adloop": {
 "command": "/absolute/path/to/adloop/.venv/bin/python",
 "args": ["-m", "adloop"]
 }
 }
}

Then install the orchestration rules + slash commands globally so every Claude Code session inherits them:

adloop install-rules

This writes a managed block to ~/.claude/CLAUDE.md and copies the slash commands (prefixed adloop-*) into ~/.claude/commands/. The block is delimited by sentinel comments so it's safe to run multiple times — re-running just refreshes the content. Two install modes:

• inline (default) — full rules embedded in ~/.claude/CLAUDE.md. Reliable but adds ~10K tokens to every Claude Code session.

• lazy (adloop install-rules --lazy) — small directive in CLAUDE.md pointing at ~/.claude/rules/adloop.md. Cheaper baseline cost; the LLM reads the rules file only when AdLoop tools are in scope.

To refresh after upgrading AdLoop: adloop update-rules. To remove cleanly: adloop uninstall-rules — only the managed block and adloop-* commands are touched, never your own content.

If you'd rather manage things by hand instead, copy .claude/rules/adloop.md and .claude/commands/ from this repo into your project's .claude/ directory.

Claude Desktop / claude.ai has no programmatic rules location. Run adloop install-rules and it will print the rules content for you to paste into Project settings → Custom instructions on claude.ai.

Use It

Ask your AI assistant things like:

• "How are my Google Ads campaigns performing this month?"

• "Which search terms are wasting budget? Add them as negative keywords."

• "My sign-up conversions dropped — check GA4 and Ads to find out why."

• "Draft a new responsive search ad for my main campaign."

• "Which landing pages get paid traffic but don't convert?"

• "Is my tracking set up correctly? Compare my codebase events against GA4."

• "What keywords should I target for [product]? Find ideas and estimate the budget."

• "How much budget would I need for these keywords in Germany?"

• "Create a new search campaign for [product feature] with a €20/day budget."

Configuration Reference

All configuration lives in ~/.adloop/config.yaml. See config.yaml.example for a documented template.

Project Structure

src/adloop/
├── __init__.py # Entry point — routes 'adloop init' to wizard, otherwise starts MCP server
├── server.py # FastMCP server — 43 tool registrations with safety annotations
├── config.py # Config loader (~/.adloop/config.yaml)
├── auth.py # OAuth 2.0 flow (bundled + custom credentials, headless fallback) + service accounts
├── cli.py # Interactive 'adloop init' setup wizard
├── crossref.py # Cross-reference tools (GA4 + Ads combined analysis)
├── tracking.py # Tracking validation + code generation tools
├── ga4/
│ ├── client.py # GA4 Data + Admin API clients
│ ├── reports.py # Account summaries, reports, realtime
│ └── tracking.py # Event discovery
├── ads/
│ ├── client.py # Google Ads API client (version-pinned) + retry/backoff for rate limits
│ ├── gaql.py # GAQL query execution with human-readable error parsing
│ ├── read.py # Campaign, ad, keyword, search term, negative keyword, shared sets, recommendations, audience reads
│ ├── pmax.py # Performance Max tools — campaign/asset group performance, asset labels, top combinations
│ ├── write.py # Draft campaign, RSA, keywords; pause, enable, remove, confirm
│ └── forecast.py # Budget estimation + keyword discovery via Keyword Planner API
└── safety/
 ├── guards.py # Budget caps, bid limits, blocked operations, Broad Match safety
 ├── preview.py # Change plans and previews
 └── audit.py # Mutation audit logging

Roadmap

What's been shipped and what's next:

• ✓

• ✓

• ✓

• ✓

• ✓

• ✓

• ✓

• ✓

• ✓ — CLAUDE.md, .mcp.json, .claude/rules/, .claude/commands/, CLI wizard snippets

• Claude Desktop one-click install — adloop install claude-desktop (and/or a .dxt extension bundle) that writes the AdLoop MCP entry into claude_desktop_config.json automatically, so Claude Desktop + Cowork users don't have to hand-edit JSON

• ✓ — pip install adloop

• ✓ — no Google Cloud project required (currently blocked at 100-user cap pending Google verification; adloop init defaults to the Custom Google Cloud Project Setup path until verification completes)

• ✓ — manual URL copy-paste flow for servers without a browser

• ✓ — 28 prompt-and-expectation tests covering read, write, tracking, and planning workflows

• Community launch — HN, Indie Hackers, r/cursor, Twitter

• Video walkthrough

Contributing

See CONTRIBUTING.md for guidelines. The short version: open an issue describing your situation first, then submit a PR if you want to build it.

License

MIT — see LICENSE.

Privacy

AdLoop runs entirely on your machine. No data is collected, stored, or transmitted to any server. See PRIVACY.md for the full privacy policy.

If AdLoop helps you run Google Ads, GA4, and tracking code from one place — give it a star.

Made by @kLOsk | Privacy Policy

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• add_negative_keywordsA
• add_to_negative_keyword_listA
• analyze_campaign_conversionsA
• attach_shared_set_to_campaignsA
• attribution_checkA
• confirm_and_applyA
• detach_shared_set_from_campaignsA
• discover_keywordsA