AdRails

AdRails (adrails.dev)

Guardrails for AI agents running your ads: an open-source, self-hosted Google Ads MCP server.

Website and docs: https://adrails.dev · MCP Registry: dev.adrails/adrails · plain-text summary for agents: https://adrails.dev/llms.txt

AdRails is a local MCP server for Google Ads. An agent may read campaigns, status and search terms as often as it likes; every write has to land in a reviewed desired-state file on disk, get diffed against live state, and clear caps that live in a policy file no AdRails tool writes. The Python package and module are still named adsops — that is the name you install and run.

Three things it does differently:

• Your keys. It runs on your machine against your own Google Cloud project and Google Ads credentials. Nothing is hosted: the only endpoint the package talks to is the Google Ads API, and credentials are read from the sources you configure (a service-account JSON file, a static token, or a secret-manager lookup).
• Your caps. Caps live in a policy file that no AdRails tool writes; with require_plan_id on, every commit must quote a fresh, single-use plan_id issued for that exact plan; and a change that adds spend exposure is refused while the scheduled guard's heartbeat is stale.
• Pay per call in sats. Optional hosted add-ons, Lightning-first, metered per call in sats — coming soon. Nothing in this release contacts any hosted service.

New in 0.8.0: a full local-business suite your AI runs after one intake interview. Five playbooks (AEO, local leads, Google Business Profile, Google Ads, ChatGPT Ads), each 90-day plan task linked to the section behind it, adsops_results before/after reports and privacy-safe case studies, adsops_gbp to get a Business Profile to 100, and a monthly prompt. Plus update awareness (adsops_update_check, adsops-mcp upgrade). 82 tools.

Common questions

What is the safest way to let an AI agent manage Google Ads? Give the agent a write path that cannot exceed limits it doesn't control. With AdRails, every change is a git-committed desired-state file, then adsops_plan (a dry-run diff), then Google's validate-only check, then a commit with a single-use plan ID. Caps live in a policy file no AdRails tool can write, and an hourly guard can only pause. Checklist: Google Ads MCP safety: 7 controls.

Is there an open-source Google Ads MCP server that runs locally? Yes. AdRails is Apache-2.0, runs on your machine over stdio with your own Google Cloud project and keys, and installs with pip install adrails. Nothing is hosted.

How do I connect Claude Code, Cursor or Grok to Google Ads? pip install adrails, then adrails init --dir DIR --customer-id ID --campaign-id N --sa KEY.json and adrails doctor, then claude mcp add adrails -- adrails --config DIR/config.json (Cursor and Grok use the same mcpServers entry). See install guides.

Can I require human approval before an AI agent changes my ad budget? Yes. Set approvals.mode to exposure (budget increases, enabling, end-date extensions) or all. The agent calls adsops_approval_request, a human approves with an HMAC-signed token that expires, and a commit without an approved plan_id is refused.

How do I audit every change an AI agent makes to my ad accounts? Every mutating call, including refused ones, is appended to a SHA-256 hash-chained log with secrets redacted. adsops_audit_verify detects edited, deleted or reordered entries. adsops_rollback rebuilds any earlier committed state, and adsops_drift flags edits made outside AdRails.

How do I check whether Google Ads conversion tracking actually works? adsops_conv_audit scores the account 0-100: no primary goal, auto-tagging off, primary actions with zero conversions, double counting, lead actions counting every click, primary actions whose goal is not biddable, spend without conversions, and smart bidding without enough data.

How can an agent check if ChatGPT, Claude and Perplexity can crawl and cite my site? aeo_site_audit checks robots.txt rules for 18 AI and search crawlers (RFC 9309), llms.txt, the sitemap, noindex and canonical tags, and whether the body text is readable without JavaScript. Free browser version: AI crawler checker.

How do I validate or build an llms.txt file? aeo_llms_txt validates a live /llms.txt against the llmstxt.org format, or builds one from a page list.

How do I track whether AI assistants recommend my business? Your agent asks ChatGPT, Claude or Perplexity your category questions and passes the answers to aeo_visibility_record. It scores mentions, rank against competitors, citations and sentiment, and reports the change since the last run. AdRails makes no LLM calls itself.

How do I track response rates and cost per lead for postcards? mail_codes_assign gives every piece a phone-readable tracking code and a UTM-tagged URL. mail_scans counts real scans from your own server logs (bots and your own test scans removed). mail_response reports rates with 95% intervals, and channel_cac puts direct mail cost per lead next to Google Ads. Free browser tools: postcard QR codes, response calculator, holdout calculator.

Does AdRails support ChatGPT Ads (the OpenAI Ads API)? Not yet. The adapter is in development; it will use the same plan, validate and commit path, with OpenAI's Bulk API validate_only and partial_failure forced off.

Testing

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

The QA suites were written adversarially by a separate agent with no write access to `adsops/`, and every finding was fixed

or documented as intended behaviour.

What AdRails cannot guarantee

Read this before pointing it at a live account.

• It is a threshold with automatic pause attempts, not a hard spend ceiling. The guard compares spend with numbers you wrote and issues pause operations. That is containment, not billing control.
• Google can deliver up to 2x the average daily budget on a given day. A daily budget is an average, not a maximum, and a pause is an API call that can be rejected or land late.
• Reporting is delayed. The spend figures AdRails reads are minutes to hours behind delivery.
• The guard only acts when it is scheduled and the machine is awake. A chat-session MCP process is not a monitor: while the machine sleeps no checks run, spend keeps moving, and the heartbeat goes stale.
• An agent with shell access as the same user can bypass any local tool. AdRails constrains the tool calls it serves, not the machine underneath. Sandbox the agent if that matters to you.
• Wrong negative keywords can suppress good traffic. Negatives are append-only here, so a bad one is also awkward to withdraw.
• You are responsible for your account and your spend. Keep platform-side billing limits as the real ceiling.

Quickstart

1. Install.

# from PyPI (https://pypi.org/project/adrails/)

pipx install adrails # console script: adsops-mcp

or run without installing:

uvx --from adrails adsops-mcp --config /absolute/path/config.json

No other dependencies. Service-account tokens are signed with your system openssl when google-auth isn't installed (install google-auth if you prefer it).

The core is stdlib-only. Check it offline (everything mocked, no network):

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

2. Write a config. Every account, credential source and path lives here; paths are ~-expanded at load time.

{

"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 defaults to require_clean_git: true and allow_commit: false, so commits and adsops_set stay off until you turn them on.

3. Write the policy file for the campaign (next section), and commit both files to git so git diff is the change review.

4. Register the server in your MCP client. Diagnostics go to stderr; the server speaks JSON-RPC 2.0 over stdio, one object per line.

{

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

5. Schedule the guard. A chat session cannot watch spend, so the pause-only spend check runs from your OS scheduler every 15 minutes. Templates for launchd, systemd and cron live in deploy/; render the placeholders (__PYTHON__, __CONFIG__, __PKG__, __LOGDIR__) and read deploy/GUARD.md before installing:

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

The command all three units run is PYTHONPATH=$PKG $PY -m adsops --config $CFG guard-all.

Use it from Grok, Claude Code, Cursor or any MCP client

AdRails is a local stdio server, so every client registers the same command. There is no hosted URL, by design.

pip install adrails

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 or a project .mcp.json:

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

Claude Desktop: install the .mcpb bundle from the latest release. More: https://adrails.dev/docs/mcp-clients/

Tools

| adsops_terms | Clicked search terms for the last N days (1–90