AdRails

AdRails（adrails.dev）

为投放广告的 AI Agent 提供护栏：一个开源、可自托管的 Google Ads MCP 服务。

网站和文档：https://adrails.dev · MCP Registry：dev.adrails/adrails · 面向 Agent 的纯文本摘要：https://adrails.dev/llms.txt

AdRails 是用于 Google Ads 的本地 MCP 服务。Agent 可以随意读取广告系列、状态和搜索字词；每次写入都必须落到磁盘上经过审核的期望状态文件中，与实时状态进行差异比较，并通过一份策略文件中的上限检查；AdRails 的任何工具都不会写入这份策略文件。Python 包和模块仍名为 adsops——这是你安装和运行时使用的名称。

它的三项不同之处：

• 你的密钥。 它在你的机器上运行，使用你自己的 Google Cloud 项目和 Google Ads 凭据。服务不会托管任何内容：该软件包唯一访问的端点是 Google Ads API，凭据则从你配置的来源读取（服务账号 JSON 文件、静态令牌或密钥管理器查询）。
• 你的上限。 上限存放在一份策略文件中，AdRails 的任何工具都不会写入这份文件；启用 require_plan_id 后，每次提交都必须附上为该确切计划签发的新鲜、一次性 plan_id；如果定时守护程序的心跳已过期，系统会拒绝任何会增加支出风险的变更。
• 按调用次数以聪支付。 可选的托管附加服务优先支持 Lightning，按调用次数以聪计费——即将推出。此版本中的任何内容都不会联系任何托管服务。

测试

python3 -m adsops --selftest           # 430 unit checks, everything mocked
python3 tests/qa_invariants.py         # 200 random sequences against a simulated Google Ads account
python3 tests/qa_inputs.py             # hostile policy/state/config inputs (NaN, Infinity, bad dates, bad UTF-8, ...)
python3 tests/qa_secrets.py            # canary tokens injected everywhere; none may reach output or logs

QA 测试套件由一个没有 adsops/ 写入权限的独立 Agent 以对抗性方式编写，所有发现的问题都已修复或记录为预期行为。

AdRails 无法保证的事项

将其用于线上账号前，请阅读以下内容。

• 它是带有自动暂停尝试的阈值，并非硬性支出上限。 守护程序会将支出与您设定的数值进行比较，并发出暂停操作。这只能起到控制作用，并非账单控制。
• Google 在某一天的投放金额最高可达平均每日预算的 2 倍。 每日预算是平均值，并非上限；暂停操作是一项可能被拒绝或延迟生效的 API 调用。
• 报告存在延迟。 AdRails 读取的支出数据比实际投放情况滞后数分钟到数小时。
• 只有在定时运行且机器处于唤醒状态时，守护程序才会采取行动。 聊天会话中的 MCP 进程并不是监控器：机器休眠时不会运行检查，支出会继续增长，心跳也会过期。
• 拥有相同用户身份的 shell 访问权限的 Agent 可以绕过任何本地工具。 AdRails 只约束它提供的工具调用，不约束底层机器。如果这对你很重要，请对 Agent 进行沙箱隔离。
• 错误的否定关键字可能会屏蔽优质流量。 这里的否定关键字只能追加，因此撤回错误的关键字也很麻烦。
• 你要对自己的账号和支出负责。 请将平台端的账单限额作为真正的上限。

快速开始

1. 安装。

# from GitHub (PyPI release coming soon)
pipx install git+https://github.com/antonioac1/adrails     # console script: adsops-mcp
# or run without installing:
uvx --from git+https://github.com/antonioac1/adrails adsops-mcp --config /absolute/path/config.json

无需其他依赖。未安装 google-auth 时，服务账号令牌会使用系统中的 openssl 签名（如果你更倾向于使用 google-auth，请安装它）。

核心部分仅依赖标准库。离线检查（所有内容均为模拟，不会访问网络）：

python3 -m adsops --selftest      # or: deploy/smoke_docker.sh

2. 编写配置。 所有账号、凭据来源和路径都在此处定义；加载时会展开路径中的 ~。

{
  "tenant": "your-tenant",
  "meter_log": "~/.adsops/meter.jsonl",
  "audit_log": "~/.adsops/audit.jsonl",
  "plan_ledger": "~/.adsops/plans.jsonl",
  "lock_dir": "~/.adsops/locks",
  "guard_heartbeat": "~/.adsops/guard.heartbeat",
  "credentials": {"google_ads": {"type": "service_account",
      "sources": [{"kind": "file", "path": "~/.adsops/sa.json"}]}},
  "google_ads": {"api_version": "v24", "end_field": "end_date_time", "login_customer_id": null},
  "commit_policy": {"require_clean_git": true, "allow_commit": true, "allow_set": true},
  "accounts": [{"key": "main", "platform": "google_ads", "customer_id": "000-000-0000",
      "campaigns": [{"key": "search_core", "state_file": "~/ads/search_core.json",
                     "policy_file": "~/ads/search_core.policy.json"}]}]
}

commit_policy 默认值为 require_clean_git: true 和 allow_commit: false，因此在启用这些选项之前，提交和 adsops_set 都会保持关闭。

3. 编写广告系列的策略文件（见下一节），并将两个文件都提交到 git，以便通过 git diff 审查变更。

4. 在 MCP 客户端中注册服务。 诊断信息会写入 stderr；服务通过 stdio 使用 JSON-RPC 2.0 通信，每行一个对象。

{
  "mcpServers": {
    "adrails": {
      "command": "python3",
      "args": ["-m", "adsops", "--config", "/absolute/path/config.json"]
    }
  }
}

5. 安排守护检查。 聊天会话无法监控支出，因此仅用于暂停的支出检查会由操作系统调度程序每 15 分钟运行一次。launchd、systemd 和 cron 的模板位于 deploy/；安装前请替换占位符（__PYTHON__、__CONFIG__、__PKG__、__LOGDIR__），并阅读 deploy/GUARD.md：

PY=$(command -v python3); CFG=/absolute/path/config.json
PKG=/absolute/dir/containing/adsops; LOGDIR="$HOME/.adsops/logs"
mkdir -p "$LOGDIR"
sed -e "s|__PYTHON__|$PY|g" -e "s|__CONFIG__|$CFG|g" \
    -e "s|__PKG__|$PKG|g" -e "s|__LOGDIR__|$LOGDIR|g" \
    deploy/launchd/com.adsops.guard.plist.template \
    > ~/Library/LaunchAgents/com.adsops.guard.plist
plutil -lint ~/Library/LaunchAgents/com.adsops.guard.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.adsops.guard.plist

这三个单元都会运行的命令是 PYTHONPATH=$PKG $PY -m adsops --config $CFG guard-all。

在 Grok、Claude Code、Cursor 或任何 MCP 客户端中使用

AdRails 是本地 stdio 服务，因此所有客户端注册相同的命令。它有意不提供托管 URL。

pip install git+https://github.com/antonioac1/[email protected]

# Claude Code
claude mcp add adrails -- python3 -m adsops --config /absolute/path/config.json
# Grok CLI (it also reads ~/.claude.json, .cursor/mcp.json and .mcp.json)
grok mcp add adrails -- python3 -m adsops --config /absolute/path/config.json

Cursor 或项目的 .mcp.json：

{"mcpServers":{"adrails":{"command":"python3","args":["-m","adsops","--config","/absolute/path/config.json"]}}}

Claude Desktop：从最新版本安装 .mcpb 包。 更多信息：https://adrails.dev/docs/mcp-clients/

工具

工具	功能
adsops_campaigns	列出此部署可操作的广告系列：键、账号、状态文件和当前提交策略。
adsops_status	读取单个广告系列的实时信息：状态、结束日期、每日预算、今日及累计支出、否定词数量、上限是否来自策略文件，以及守护检查心跳的时间。
adsops_terms	获取过去 N 天（1–90 天，默认 14 天）的点击搜索词：搜索词、匹配的关键词、点击次数、费用。
adsops_plan	将期望状态文件与实时状态进行纯差异比较，不写入任何内容。返回操作、备注、ops_count、发现的风险敞口增加项，以及带有有效期的一次性 plan_id。
adsops_apply	除非设置 commit=true，否则仅验证。提交需要 commit_policy.allow_commit、处于干净 git 跟踪状态的状态文件、在变更增加风险敞口时提供新鲜的守护检查心跳，以及在策略要求时提供来自 adsops_plan 的 plan_id。
adsops_set	提议更改预算／状态／结束日期／否定词，并附上简短的 reason；根据策略上限和实时状态进行检查，将状态文件写入磁盘并提交到 git。dry_run=true 会返回 plan_id 而不写入；在策略要求时，apply=true 需要提供该 plan_id。
adsops_guard	读取支出，并在超过每日或累计阈值时暂停广告系列。仅用于暂停：绝不会启用广告系列、提高预算或编辑关键词。除非设置 commit=true，否则仅验证。
adsops_usage	租户用量汇总：每个工具的调用次数、错误数、单位数、操作数和延迟中位数。

策略文件

每个广告系列对应一个策略文件，并在配置中通过 policy_file 引用。AdRails 只会读取该文件：没有工具会写入上限，且 adsops_set 会直接拒绝 guards 和 allow_enable。如果状态文件中也包含上限，则会被忽略——策略文件始终优先，adsops_status 会说明这一点。

{
  "customer_id": "000-000-0000",
  "campaign_id": 1000000000,
  "guards": {
    "max_daily_budget_usd": 40,
    "min_daily_budget_usd": 5,
    "max_end_date": "2026-12-31",
    "lifetime_spend_pause_usd": 900,
    "daily_spend_pause_usd": 60,
    "max_ops_per_run": 12
  },
  "allow_enable": false,
  "max_guard_age_min": 30,
  "require_plan_id": true,
  "plan_ttl_s": 900
}

字段	含义
customer_id	广告系列所属的账户；去除短横线后与状态文件比较。不匹配时会拒绝操作。
campaign_id	此策略所管控的唯一广告系列；必须与状态文件完全匹配。
guards.max_daily_budget_usd	必填。每日预算上限，也是规划时检查的预算上限。
guards.min_daily_budget_usd	可选。每日预算下限；不得高于上限。
guards.max_end_date	必填，格式为 YYYY-MM-DD。任何计划可设置的最晚结束日期。
guards.lifetime_spend_pause_usd	必填。触发防护机制发出暂停指令的总支出金额。
guards.daily_spend_pause_usd	必填。触发防护机制发出暂停指令的今日支出金额。
guards.max_ops_per_run	必填整数。单次运行最多可发出的操作数；超出时会拒绝。
allow_enable	默认为 false。计划是否可以将广告系列设为 ENABLED。
max_guard_age_min	默认为 null（关闭检查）。设置后，任何会增加支出风险的更改都会被拒绝，除非防护机制的心跳时间距今不超过此值。
require_plan_id	默认为 false。设为 true 时，apply/commit 以及带有 apply=true 的 adsops_set 必须提供 plan_id。
plan_ttl_s	默认为 900，范围为 60–86400。已签发的 plan_id 可使用的时长；每个 plan_id 只能使用一次。

缺失或格式错误的字段会导致错误，并指出字段名称，而不会静默使用默认值。

期望状态文件

每个广告系列对应一个 JSON 文件，并通过 state_file 引用。文件描述广告系列应有的状态；服务会计算差异。

{
  "customer_id": "000-000-0000",
  "campaign_id": 1000000000,
  "campaign_name": "Search - Core",
  "status": "PAUSED",
  "end_date": "2026-11-30",
  "daily_budget_usd": 20,
  "negatives_add": [
    {"text": "free", "match_type": "BROAD"},
    {"text": "cheap", "match_type": "PHRASE"}
  ],
  "guards": {
    "max_end_date": "2026-12-31",
    "min_daily_budget_usd": 5,
    "max_daily_budget_usd": 40,
    "lifetime_spend_pause_usd": 900,
    "daily_spend_pause_usd": 60,
    "max_ops_per_run": 12
  }
}

字段	含义
customer_id	广告系列所属的账户；使用前会去除短横线。
campaign_id / campaign_name	此文件负责管理的唯一广告系列。两者都必须与实时状态匹配，否则运行会中止。
status	期望的状态，ENABLED 或 PAUSED。若设为 ENABLED，还必须在策略中启用 allow_enable。
end_date	期望的结束日期，格式为 YYYY-MM-DD，不得晚于 guards.max_end_date，且不能早于当前日期。
daily_budget_usd	期望的每日预算，必须在防护机制规定的上下限范围内。
negatives_add	仅追加的 {text, match_type} 列表；匹配类型为 BROAD、PHRASE 或 EXACT。此处的任何内容都不会移除关键字。
guards	仅在广告系列未配置 policy_file 时读取（旧版模式）。配置了策略文件后，此处的内容会被忽略。

将这些文件保存在 git 中。这才能让“经过审核的期望状态”成为现实：git diff 用于审查更改，而 require_clean_git 会使服务拒绝执行未提交的编辑。

可与 Google 官方只读版 google-ads-mcp 配合使用

在同一个 MCP 客户端中同时运行两个服务。Google 的服务负责临时 GAQL 探索，且不会写入；AdRails 是唯一的写入途径。Agent 使用官方服务读取数据，提出对期望状态文件或策略文件的更改，然后通过 adsops_plan / adsops_apply 应用——中间会执行上限检查、验证、账户锁定，并写入审计记录。两者都通过 stdio 使用 JSON-RPC，因此每个服务只需在 .mcp.json 中添加一条配置。

许可证

Apache-2.0。