AdLoop
The AI command center for Google Ads, Reddit Ads, GA4, and tracking code.
Power your agent
URL ของผู้เผยแพร่เอง ไม่ใช่เอนด์พอยต์ของ PlugMCP
Host a copy with our keys and logs.
https://mcp.getadloop.com/mcpปุ่ม Claude ด้านบนจะเปิด Claude พร้อมกรอกชื่อและ URL ให้แล้ว คุณยังต้องยืนยันที่นั่นเอง
claude mcp add --transport http klosk-adloop https://mcp.getadloop.com/mcpRun in a terminal.
{ "mcpServers": { "klosk-adloop": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.getadloop.com/mcp" ] } }}claude_desktop_config.json
URL แบบรีโมตหรือคำสั่งบนเครื่องของคุณ? การติดตั้งสองแบบต่างกันอย่างไร
รันบน PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
เปิด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.
Both versions run the same tools with the same safety model. The difference is who handles the plumbing:
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.
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.
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.
Quick start:
pip install adlooporgit clone https://github.com/kLOsk/adloop.git && cd adloop && uv sync && uv run adloop init— or zero setup on AdLoop Cloud
Brand lists — a list is a
SharedSetof typeBRANDS; attaching it to a campaign is aCampaignCriterion.brand_list(negative=trueexcludes,falserestricts), not aCampaignSharedSetlike negative keyword lists.remove_from_brand_listanddetach_brand_list_from_campaignsremove for real —SharedCriterionhas 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_brandsfor a single name orcheck_brand_namesfor a shortlist to get the ID;exact_matchmarks 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_exclusionssets 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_settingsis 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_goalsshows the goals with their actions and a campaign's current goal config;draft_custom_conversion_goalcreates a set,draft_update_custom_conversion_goalrenames or replaces its actions,draft_assign_custom_conversion_goalpoints a campaign at it anddraft_clear_custom_conversion_goalputs 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, andget_ad_performanceacceptcompact=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.
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.
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.
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.
Safety gates specific to GTM:
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.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.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.jsonand run any tool to re-consent — until then GTM tools return a permissions error.
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 withget_keyword_performanceto find paid/organic cannibalization and untapped keyword opportunities.
A second ad platform, same safety model. Reddit is a separate connection: its own developer app, its own OAuth, no developer token and no approval process. Every tool takes ad_account_id (defaults to reddit.ad_account_id).
Setup for Reddit Ads tools — In Reddit Ads Manager open Business Manager → Developer Application → Create app (business admins only; no approval wait). Register the redirect URL exactly as
http://localhost:8765/callback, then runadloop initand complete the Reddit Ads step: it opens Reddit's consent page (scopesadsread+adsedit, permanent grant), stores the refresh token at~/.adloop/reddit_token.json, and lets you pick the default ad account. Reddit rate-limits per user (reporting: 60 requests/min) and requires a descriptive User-Agent, which AdLoop builds from your app id and Reddit username. Reddit has no validate-only mode, soconfirm_and_apply(dry_run=true)re-reads the target and re-checks the safety caps instead.
An image on your computer, or one you attached in the chat, has no public URL, and an AI app cannot hand the file to a tool. upload_images gives it a way in.
The upload ids go into draft_image_assets(upload_ids=[...]), or as upload:<id> into the image fields of draft_reddit_ad on AdLoop Cloud.
All write operations follow a draft → preview → confirm workflow. Nothing executes without explicit approval.
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/rules/adloop.mdc (canonical source).claude/rules/adloop.md (synced from Cursor rules via scripts/sync-rules.py)The rules include:
AdLoop includes pre-built slash commands in .claude/commands/ for common workflows:
AdLoop manages real ad spend, so safety is not optional.
confirm_and_apply(dry_run=false) is refused with APPROVE_ON_CARD, whatever it was told in the chat.confirm_and_apply call is required to execute.confirm_and_apply defaults to dry_run=true. Real changes require explicit dry_run=false.safety.two_phase_apply: true, confirm_and_apply refuses dry_run=false until the plan has completed one dry-run pass — preview-then-apply becomes server-enforced instead of a convention.~/.adloop/audit.log.draft_campaign refuses BROAD keywords unless the campaign uses Smart Bidding, and draft_keywords / draft_ad_group mark them as dangerous in the preview, so the AI has to raise it before anything is applied.health_check warns when a newer version is available.readOnlyHint so they work in Cursor's Ask mode without switching to Agent mode.AdLoop uses your own (free) Google Cloud project for OAuth. The
adloop initwizard walks you through it — a one-time setup of about 5 minutes, with no shared user caps and no waiting on anyone's verification review. AdLoop does not ship built-in OAuth credentials.Prefer zero setup? AdLoop Cloud is the hosted version: connect Google in two clicks — no Cloud project, no API access application, EU-hosted.
(Upgrading from ≤0.9 with built-in credentials? Those sign-ins were retired in 0.10 — run
adloop initonce to switch to your own project.)
[!IMPORTANT] Seeing
deleted_client: The OAuth client was deleted.orinvalid_client? The shared Google Cloud project behind AdLoop ≤0.9's bundled credentials has been shut down, so its stored sign-ins no longer refresh. Two ways forward: AdLoop Cloud (connect Google in two clicks, nothing to configure) or stay self-hosted withpip install -U adloop && adloop initto set up your own free Google Cloud project. Details in the pinned issue (#49).
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
adloop init doesThe wizard first asks whether to set up Google. Answer no to run AdLoop on Reddit Ads alone: it skips steps 1 to 6 and goes straight to the Reddit step. Otherwise it walks you through:
Since 9 September 2026, Google Ads API access belongs to the Google Cloud project that owns your OAuth client. Developer tokens are sunset: the API ignores the header, the wizard's token prompt is optional, and you no longer need a Manager Account to get access.
Apply on your project's Google Ads API Overview page in the Cloud Console:
Projects on a Cloud free trial or with billing disabled are refused Explorer and Basic; use a project with billing set up.
Getting
CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION? Your project is at Test level. Open the Overview page above and apply for Explorer access.
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.
The wizard refers to these steps — do them in your browser before running adloop init (or while it waits at the OAuth prompt).
~/.adloop/credentials.jsonService accounts are also supported — just place the service account key JSON at the same
credentials_path. AdLoop detects the file type automatically.
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:
~/.claude/CLAUDE.md. Reliable but adds ~10K tokens to every Claude Code session.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.
Ask your AI assistant things like:
All configuration lives in ~/.adloop/config.yaml. See config.yaml.example for a documented template.
Most MCP clients (claude.ai, ChatGPT, Cursor, …) load every tool schema into the model's context at the start of every conversation. With AdLoop's full catalog that's a noticeable share of the context window, paid before you type a word. If you only use part of AdLoop, expose a subset with the ADLOOP_TOOLSETS environment variable in your MCP client's env block (the adloop init wizard offers this and writes it into the snippets for you):
"env": { "ADLOOP_TOOLSETS": "ads,ga4" }
Google Ads can be narrowed further. Use one of these instead of ads:
health_check and confirm_and_apply are always included, whatever you select. Unset = the full catalog; unknown names fail at startup with the valid list. The effect is real: ads:read,ga4 costs about 40% of ads,ga4 for audits and diagnosis, and an ads:plan-only client for keyword research pays about 5% of the full catalog. Toolsets are per client, not per install: one AdLoop config can serve a trimmed Cursor and a full-catalog Claude Code side by side.
On AdLoop Cloud, the same feature is per API key: pick toolsets when creating a key in the dashboard, and that key's tools/list is trimmed server-side for whichever AI client uses it.
src/adloop/
├── __init__.py # Entry point — routes 'adloop init' to wizard, otherwise starts MCP server
├── server.py # FastMCP server — every tool registration with safety annotations and toolset tags
├── config.py # Config loader (~/.adloop/config.yaml)
├── auth.py # OAuth 2.0 flow (user-supplied credentials, headless fallback) + service accounts; GA4 / Ads / GTM scopes
├── cli.py # Interactive 'adloop init' setup wizard
├── crossref.py # Cross-reference tools (GA4 + Ads + GTM 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
├── gtm/
│ ├── client.py # Google Tag Manager API v2 client
│ └── read.py # Live container fetching, tag/trigger/variable parsing, workspace diff, version history
├── reddit/
│ ├── auth.py # Reddit OAuth2 (own app, permanent refresh token, loopback flow for adloop init)
│ ├── client.py # Reddit Ads API v3 REST client — bearer refresh, per-user rate limits, pagination
│ ├── read.py # Accounts, campaigns, ad groups, ads, performance reports, pixels, targeting lookups
│ └── write.py # Draft/preflight/apply for status, budget, bid, targeting, and PAUSED creation
└── safety/
├── guards.py # Budget caps, bid limits, blocked operations, Broad Match safety
├── preview.py # Change plans and previews
└── audit.py # Mutation audit logging
What's been shipped and what's next:
adloop init)CLAUDE.md, .mcp.json, .claude/rules/, .claude/commands/, CLI wizard snippetsadloop 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 JSONpip install adlooptests/evals/ covering read, write, tracking, and planning workflowsaudit_event_coverage three-way join across codebase events, GTM tags, and GA4 actual firesSee CONTRIBUTING.md for guidelines. The short version: open an issue describing your situation first, then submit a PR if you want to build it.
MIT — see LICENSE.
The open-source version runs entirely on your machine. No data is collected, stored, or transmitted to any server. See PRIVACY.md for the full privacy policy. AdLoop Cloud has its own privacy policy and DPA.
If AdLoop helps you run Google Ads, GA4, and tracking code from one place — give it a star or try the hosted version.
Made by @kLOsk | AdLoop Cloud | Privacy Policy
Google Ads MCP server for Claude, ChatGPT and Cursor, with Reddit Ads, GA4 and Tag Manager. Every change is previewed first.
{ "mcpServers": { "klosk-adloop": { "url": "https://mcp.getadloop.com/mcp", "headers": {} } }}เครื่องมือ
ยังไม่มีรายการเครื่องมือ เซิร์ฟเวอร์แบบรีโมตจะได้รายการหลังการตรวจสอบสถานะครั้งแรก
FAQ
คัดลอกคอนฟิก http สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
ระเบียนนี้ไม่ได้ระบุตัวแปรสภาพแวดล้อมที่จำเป็น
Adloop เข้าถึงได้ผ่าน HTTP
ตรวจสอบล่าสุดเมื่อ 2026-11-16 Google Ads MCP server for Claude, ChatGPT and Cursor, with Reddit Ads, GA4 and Tag Manager. Every change is previewed first.