adloop (K L Osk)

AdLoop

谷歌广告、GA4和跟踪代码的人工智能指挥中心。

      ](https://github.com/kLOsk/adloop)

MCP服务器，为您的AI助手提供对Google Ads和GA4的读写访问权限，并配有防止意外支出的安全护栏。

pip install adloop

______________________________________________________________________

它解决了什么

AdLoop的存在是因为将Google Ads与代码一起管理是一团糟。以下是它处理的具体问题：

• “我的转化率下降了，我不知道为什么。” AdLoop在一个查询中交叉引用广告点击、GA4会话和转换事件。它可以检测差距是来自GDPR同意拒绝、跟踪中断还是实际的登录页面问题，然后再浪费时间分别检查每个仪表板。

• “我在无关的搜索上浪费广告支出。” 从IDE中的单个对话中提取搜索词报告，识别垃圾，并添加负面关键字。没有上下文切换到广告UI。

• “我的追踪还能用吗？” 将实际代码库中的事件名称与GA4接收到的事件名称进行比较。找出不匹配之处：你触发的GA4从未见过的事件，你不知道的GA4记录的事件。

• “我需要创建广告，但谷歌广告的用户界面是敌对的。” 起草响应式搜索广告、创建活动、添加关键字——所有这些都是通过自然语言完成的。每次更改都会先显示预览。没有你的明确确认，任何东西都不会上线。新广告和活动开始暂停。

• “我的登录页面获得了付费流量，但没有人转换。” AdLoop将您的广告最终URL与GA4页面级数据连接起来。查看哪些页面获得了点击但没有转化，哪些页面的跳出率很高，哪些页面在任何广告活动中都是孤立的。

• “我不知道我的欧盟同意设置是否造成了数据缺口。” 在欧洲，30-70%的用户拒绝分析Cookie。AdLoop会自动解释这一点——它不会将正常的GDPR同意差距诊断为跟踪中断。

从实际使用中构建

每个工具的存在都是因为在运行真实的谷歌广告活动时遇到了实际问题。交叉引用工具的存在是因为我们一直在手动要求人工智能“获取广告数据，然后获取GA4数据，然后进行比较”，因此我们实现了连接的自动化。广泛匹配+手动CPC安全规则之所以存在，是因为人工智能曾经创造了这种精确的组合，浪费了预算。GDPR同意意识之所以存在，是因为人工智能一直将正常的欧盟cookie拒绝诊断为错误的跟踪。

最好的功能来自真实的工作流程。如果你在使用AdLoop，发现自己希望它能做一些它做不到的事情， 打开一个描述你情况的问题 --不仅仅是“添加功能X”，而是“我试图做Y，但做不到，因为Z。”上下文比请求更重要。

全部43个工具

快速启动： pip install adloop 或 git clone https://github.com/kLOsk/adloop.git && cd adloop && uv sync && uv run adloop init

诊断

GA4读取工具

谷歌广告阅读工具

交叉引用工具（GA4+广告组合）

这些工具在内部调用这两个API，并返回具有自动生成见解的统一结果。它们是AdLoop与单独的GA4和广告工具不同的核心。

跟踪工具

规划工具

Google广告撰写工具

所有写入操作都遵循 草稿→ 预览→ 确认 工作流程。未经明确批准，不得执行任何操作。

编排规则

AdLoop附带了指导人工智能的编排规则 *怎么* 结合这些工具——营销工作流程、GAQL语法、安全协议、GDPR意识和最佳实践。没有规则，人工智能有工具，但不知道剧本。

• 光标: .cursor/rules/adloop.mdc （权威来源）
• 克劳德代码: .claude/rules/adloop.md （通过以下方式从游标规则同步 scripts/sync-rules.py)

这些规则包括：

• 编排模式 用于常见工作流程（绩效评估、转化诊断、活动创建、负面关键字卫生、关键字发现、跟踪验证、预算规划、登录页分析）
• GAQL快速参考 具有语法、常见查询和陷阱
• 安全规则 包括广泛匹配+手动CPC预防和预写验证
• 广告文案字符限制指南 （30个字符的标题比你想象的要短）
• GDPR同意意识 防止欧盟市场出现错误的跟踪诊断

Slash命令（克劳德代码）

AdLoop中包含预构建的斜线命令 .claude/commands/ 对于常见工作流：

安全模型

AdLoop管理真实的广告支出，因此安全性不是可选的。

• 两步写。 每个突变都会首先返回预览。一个单独的 confirm_and_apply 需要调用才能执行。
• 默认情况下为干运行。 甚至 confirm_and_apply 默认为 dry_run=true真正的改变需要明确 dry_run=false.
• 预算上限。 可配置的每日最大预算——服务器拒绝任何超过上限的预算。
• 审核日志。 每次操作（包括干运行）都记录在 ~/.adloop/audit.log.
• 新的活动和广告暂停。 没有手动启用，任何东西都无法上线。
• 破坏性行动需要双重确认。 删除实体或大幅增加预算会触发额外警告。
• 宽赛+手动CPC被阻止。 广告支出浪费的首要原因被自动阻止-- draft_keywords 拒绝在没有智能竞价的情况下将BROAD匹配关键字添加到广告系列中。
• 预写验证。 在任何写入之前，AI都会检查出价策略、转化跟踪状态和质量分数。如果广告活动从根本上被破坏了，AdLoop会警告你，而不是让事情变得更糟。
• 结构化错误处理。 所有工具都会返回带有提示的可操作错误消息，而不是原始异常。身份验证错误包括特定的重新授权步骤。
• API版本固定。 Google Ads API版本是固定的，以防止库更新中的无声破坏更改。 health_check 当有新版本可用时发出警告。
• 询问模式兼容性。 阅读工具声明 readOnlyHint 因此，它们在Cursor的Ask模式下工作，而无需切换到Agent模式。

设置

⚠️ 在Google验证等待期间，内置OAuth凭据暂时不可用。 谷歌将未经验证的OAuth应用程序限制为100名用户，而AdLoop已经达到了这一上限。新用户将看到 “此应用程序已被阻止” 如果他们在向导中选择内置选项，则会出错。 这对你意味着什么： 直到谷歌完成验证， 带上你自己的谷歌云项目 --它需要大约5分钟，没有用户上限 adloop init 向导将引导您完成此过程。状态更新： 讨论#13. *（在上限之前已经发行代币的现有用户继续工作——只有首次登录才会被阻止。）*

安装

来自PyPI：

pip install adloop
adloop init

来源：

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

什么 adloop init 做

在验证等待期间，向导默认为“自带Google Cloud项目”路径。它将引导您通过：

1. 谷歌云设置 --创建项目，启用三个API，生成OAuth客户端（请参见 自定义谷歌云项目设置 下面是向导为您推荐的确切步骤）
2. 开发者代币 --从您的Google广告MCC(API中心)
3. MCC帐户ID --您的经理帐户ID（MCC UI中的顶部栏）
4. OAuth登录 --打开浏览器以使用Google登录（或打印无头服务器的URL）
5. 自动发现您的帐户 --自动查找您的GA4属性和广告帐户
6. 安全默认值 --预算上限和模拟运行偏好
7. 编辑器配置片段 --打印Cursor和Claude代码的MCP配置

该向导仍然为令牌早于上限的现有用户提供AdLoop的内置凭据作为非默认选项。为全新的谷歌帐户选择该选项将在同意屏幕上失败——向导会在您选择之前警告您。

需求

• Python 3.11+
• 带有MCC（经理帐户）的Google Ads帐户
• 谷歌广告开发者代币（见下文）

谷歌广告开发者代币

开发人员令牌是 始终需要 --即使在使用AdLoop的内置OAuth凭据时也是如此。内置凭据处理谷歌登录；开发者令牌是一个单独的密钥，允许API访问您的Google Ads数据。

1. 创建MCC （免费）在 ads.google.com/home/tools/manager帐户 如果你没有。将您的常规Google Ads帐户链接到它。
2. 在MCC中，转到 工具和设置→ API中心
3. 你的 开发者令牌 如图所示。复制它——向导会要求它。

访问级别 --令牌的访问级别决定了它可以做什么：

获得 DEVELOPER_TOKEN_NOT_APPROVED? 您的令牌处于“测试帐户”级别。首选 API中心 在您的MCC中，检查您的访问级别。如果它显示“测试帐户”，您需要申请基本访问权限，或者在第一次生产API调用后等待授予Explorer访问权限。

无头服务器

在没有浏览器的服务器上运行（VM、Docker、SSH）？向导会自动检测到这一点，并返回手动流程：它会打印一个可以在任何设备上打开的授权URL，然后将重定向URL粘贴回终端。

自定义谷歌云项目设置

这是默认路径，而内置凭据被谷歌的100个用户上限阻止。向导会参考这些步骤——在运行之前在浏览器中执行这些步骤 adloop init （或者在等待OAuth提示时）。

第一步——谷歌云项目

1. 首选 console.cloud.google.com 并创建一个新项目
2. 启用这三个API（在API库中搜索每个API）：

- 谷歌分析数据API --GA4报告和事件 - Google Analytics管理员API --用于列出GA4房产 - 谷歌广告API --适用于所有广告操作

步骤2-OAuth凭据

1. 在您的Google Cloud项目中，转到 API和服务→ 凭证
2. 点击 创建凭据→ OAuth客户端ID
3. 选择 桌面应用程序 作为应用程序类型，为其命名
4. 下载JSON文件并将其另存为 ~/.adloop/credentials.json

还支持服务帐户——只需将服务帐户密钥JSON放在相同的位置 credentials_path.AdLoop会自动检测文件类型。

步骤3--连接到编辑器

光标 --添加到您的项目 .cursor/mcp.json:

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

然后复制 .cursor/rules/adloop.mdc 从这个仓库到你的项目 .cursor/rules/ 目录。

克劳德代码 --运行：

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

或添加到您的项目 .mcp.json:

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

然后全局安装编排规则+斜线命令，以便每个Claude Code会话都继承它们：

adloop install-rules

这会将托管块写入 ~/.claude/CLAUDE.md 并复制斜线命令（前缀 adloop-*)进入 ~/.claude/commands/该块由哨兵注释分隔，因此多次运行是安全的——重新运行只会刷新内容。两种安装模式：

• 内联 （默认）--嵌入完整规则 ~/.claude/CLAUDE.md。可靠，但为每个Claude Code会话增加了约10K个令牌。
• 懒惰 (adloop install-rules --lazy)--小指令 CLAUDE.md 指着 ~/.claude/rules/adloop.md基线成本更低；LLM仅在AdLoop工具在作用域内时读取规则文件。

升级AdLoop后刷新： adloop update-rules。要干净地移除： adloop uninstall-rules --仅管理块和 adloop-* 命令是触摸的，而不是你自己的内容。

如果你宁愿手工管理，也可以复制 .claude/rules/adloop.md 和 .claude/commands/ 从这个仓库到你的项目 .claude/ 目录。

克劳德桌面/Claude.ai 没有程序化规则位置。跑 adloop install-rules 它将打印规则内容，供您粘贴到项目设置中→ claude.ai上的自定义说明。

用它

问你的AI助手一些事情，比如：

• *“我的谷歌广告活动本月表现如何？”*
• *“哪些搜索词在浪费预算？将其添加为负面关键字。”*
• *“我的注册转化率下降了——看看GA4和广告，找出原因。”*
• *“为我的主要活动起草一个新的响应式搜索广告。”*
• *“哪些登录页面获得了付费流量，但没有转换？”*
• *“我的跟踪设置是否正确？将我的代码库事件与GA4进行比较。”*
• *“我应该为\[产品\]定位哪些关键字？寻找想法并估算预算。”*
• *“在德国，这些关键字需要多少预算？”*
• *“以20欧元/天的预算为\[产品功能\]创建一个新的搜索活动。”*

配置参考

所有配置都存在 ~/.adloop/config.yaml。参见 config.yaml.example 用于记录模板。

项目结构

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

路线图

已发货和下一步：

• ~~GA4读取工具~~✓
• ~~带有安全层的谷歌广告读写工具~~✓
• ~~交叉参考情报（战役）→转换映射、登录页面分析、归因比较）~~✓
• ~~跟踪实用程序（根据GA4验证事件，生成gtag代码）~~✓
• ~~预算估算+通过关键字规划师发现关键字~~✓
• ~~共享否定关键词列表（SharedSet API）~~✓
• ~~重试/回退API速率限制~~✓
• ~~安装向导(adloop init)~~ ✓
• ~~克劳德代码支持~~✓ — CLAUDE.md, .mcp.json, .claude/rules/, .claude/commands/，CLI向导片段
• Claude Desktop一键安装 — adloop install claude-desktop （和/或 .dxt 扩展包），将AdLoop MCP条目写入 claude_desktop_config.json 自动，因此Claude Desktop+Cowork用户不必手动编辑JSON
• ~~PyPI包~~✓ — pip install adloop
• ~~绑定OAuth凭据~~✓ — 无需Google Cloud项目(目前限制在100个用户上限 等待谷歌验证； adloop init 默认为 自定义谷歌云项目设置 路径，直到验证完成）
• ~~无头服务器支持~~✓ — 无浏览器的服务器的手动URL复制粘贴流程
• ~~行为评估套件~~✓ — 28 涵盖读、写、跟踪和规划工作流程的提示和期望测试
• 社区启动 --HN、独立黑客、r/cursor、推特
• 视频演练

贡献

看 贡献.md 作为指导方针。简短的版本：首先打开一个描述你的情况的问题，然后如果你想建立它，提交一个PR。

许可证

麻省理工学院——见 许可证.

隐私

AdLoop完全在您的机器上运行。不会收集、存储或传输任何数据到任何服务器。看 隐私.md 了解完整的隐私政策。

______________________________________________________________________

如果AdLoop帮助您从一个地方运行Google Ads、GA4和跟踪代码-- 给它一颗星.