Skip to main content

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.4.1: 50 tools. Enterprise controls (roles, human approvals with signed tokens, a hash-chained audit log, rollback, drift detection, aggregate caps, SBOM), diagnostics (conversion-tracking audit, wasted spend, impression share, quality score, anomalies), automation that only proposes (rules, monitors, budget reallocation), an AEO toolkit (AI-crawler, page, JSON-LD and llms.txt audits, share of answer, IndexNow, AI traffic, ads-to-answers), and direct-mail tracking (list hygiene, phone-readable codes with a proven check character, QR, print-exact labels, scan counting, cost per lead across channels). Plus adrails init / adrails doctor. ChatGPT Ads support is in development, not released.

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

Tool What it does
adsops_campaigns Lists the campaigns this deployment may operate: keys, accounts, state files, and the active commit policy.
adsops_status Live read for one campaign: status, end date, daily budget, spend today and lifetime, negative count, whether caps come from the policy file, and the guard heartbeat's age. When the state file manages URL fields it also returns urls: the campaign final URL suffix and, per ad group, its custom parameters, final URL suffix and the final URLs of each enabled ad.
adsops_terms Clicked search terms for the last N days (1–90, default 14): term, matched keyword, clicks, cost.
adsops_plan Pure diff of the desired-state file against live state; writes nothing. Covers budget, status, end date, negatives and the URL fields below. Returns the operations, notes (one url: ... line per URL change), ops_count, the exposure increases it found, and a single-use plan_id with its expiry.
adsops_apply Validate-only unless commit=true. A commit needs commit_policy.allow_commit, a clean git-tracked state file, a fresh guard heartbeat when the change adds exposure, and the plan_id from adsops_plan when the policy requires it.
adsops_set Proposes a budget / status / end-date / negatives change with a short reason; checks it against policy caps and live state, writes the state file and commits it to git. dry_run=true returns a plan_id instead of writing; apply=true needs that plan_id when the policy requires it.
adsops_guard Reads spend and pauses the campaign if the daily or lifetime threshold is crossed. Pause only: it never enables, raises a budget or edits keywords. Validate-only unless commit=true.
adsops_usage Metering summary for the tenant: calls, errors, units, ops and median latency per tool.
adsops_negatives_suggest Read-only. Classifies the last N days (1–90, default 30) of search terms (renter, job, HOA/condo, vacation, DIY/software, out-of-area, competitor brand) with deterministic rules and an optional local-model hook you supply, and proposes PHRASE negatives with cost and click evidence. Skips terms and phrases your existing negatives already cover, never suggests words on your protect list, and returns a ready-to-paste negatives_add patch plus a basis note. It writes nothing: the patch goes through the desired-state file like any other change.
adsops_lp_diagnose Read-only. Per ad group, Google's quality-score components (expected CTR, ad relevance, landing page experience) plus a plain HTTP check of each final URL: status, response time, bytes, and whether the title and H1 echo the ad group's keywords and town. Returns plain-English findings, worst first. No browser and no JavaScript, so a headline built by script shows as missing.
adsops_competitors_report Read-only. The AdRails Intel weekly report from the free sources (Auction Insights you imported, cached Transparency Center data, your own stats snapshots). Needs intel_config in the config; makes no network call.
adsops_auction_insights_import Imports an Auction Insights CSV/TSV export or a pasted table into the local intel database (replaces rows for the same date range). Writes only that local SQLite file. Needs intel_config.

New in 0.4.0: enterprise controls, automation and an AEO toolkit (28 tools)

Tool What it does
adsops_conv_audit Read-only. Audit conversion tracking for the campaign's account: primary goals, dead tags, double counting, auto-tagging, lead counting, smart bidding without enough conversions. Returns a 0-100 score, grade, and ranked findings with fixes. Run this before trusting any CPA or optimising toward conversions.
adsops_diagnostics Read-only PPC diagnostics bundle for one campaign: wasted spend (zero-conversion search terms), impression share lost to budget vs rank, cost-weighted quality score with weak components, and day-over-baseline anomalies (z-score). Returns a ranked headline list plus details.
adsops_rsa_validate Pure check, no account access. Validate a Responsive Search Ad draft against Google's limits and common disapproval causes (lengths incl. double-width chars, pins, duplicates, caps, punctuation, phone numbers, unsubstantiated superlatives, banned phrases) before any write. Returns errors, warnings and fixes.
adsops_rules_check Read-only. Evaluate the automation rules in the campaign's POLICY file (founder-owned, agents can't edit it) against live metrics. Returns PROPOSALS and a desired-state patch; nothing is applied. Rules can only pause, add negatives, alert, or move budget inside the policy caps.
adsops_monitor_check Read-only. Run monitors (CPA spike, pacing over/under, month forecast, zero impressions, disapprovals, budget-limited) over live snapshots of every configured campaign (or one). New alerts are de-duplicated for 24 h; with deliver=true they are posted to the webhook named in config alerts.webhook_env.
adsops_brief Read-only. A short markdown brief across every configured campaign: spend today, conversions, blended CPA and the top issues from the monitors. Built for a daily Slack/email post.
adsops_fleet Read-only. Fleet view across every configured account and campaign: spend, budget, conversions and CPA by account and platform, plus the AGGREGATE cap check (config fleet_caps), which assumes platforms may deliver up to 2x the daily budget.
adsops_realloc_suggest Read-only. Recommend moving daily budget from weak campaigns to budget-limited strong ones inside each policy's caps. The total never rises. Returns moves plus per-campaign desired-state patches to review.
adsops_drift Read-only. Who changed the account outside AdRails? Reads Google's change history for the last N days (max 30) and flags out-of-band edits (UI, scripts, auto-applied recommendations), highlighting budget, status and bidding changes.
adsops_keyword_ideas Read-only. Keyword Planner ideas (searches, competition, top-of-page bid range) for seed keywords and/or a URL, clustered by theme with an intent label. Needs a Basic-access developer token.
adsops_offline_conv_plan Build (never send) an offline / enhanced conversion upload from CRM rows. Emails, phones and names are normalised and SHA-256 hashed LOCALLY, so raw PII never leaves this machine. Returns a redacted preview and counts; validate_only stays true.
adsops_history Read-only. Git history of the campaign's desired-state file: every change agents or lanes made, newest first.
adsops_rollback Undo: build the desired state as of an earlier commit (guards, account and campaign ids are never reverted, and negatives are never removed). With commit=true it writes and git-commits the state file; then run adsops_plan and adsops_apply as usual. Nothing reaches the ad account from this tool.
adsops_approval_request Ask a human to approve a plan before it can be committed (when config approvals.mode is on). Returns approve/reject tokens to send to the approver; the tokens are HMAC-signed and expire.
adsops_approval_decide Record a human decision using a signed approve/reject token. Forged, expired or reused tokens are refused.
adsops_approvals List approval requests (newest first), optionally by status.
adsops_audit_verify Verify the tamper-evident audit chain of every mutating call (hash-linked entries). Returns ok, entry count, the first bad entry if any, and a head digest to publish so later truncation is detectable.
adsops_audit_tail The last N audit-chain entries (redacted), newest first.
adsops_sbom Supply-chain manifest of this AdRails install: a CycloneDX 1.5 SBOM and a SHA-256 manifest of every package file, so you can verify the code you run is the code that was released.
adsops_whoami This server's identity and controls: version, principal and roles (RBAC), approval mode, audit chain path, and whether a guard heartbeat is configured.
aeo_site_audit Read-only. Can AI answer engines reach this site? Checks robots.txt rules for 18 AI and search crawlers (GPTBot, OAI-SearchBot, ChatGPT-User, ClaudeBot, Claude-User, PerplexityBot, Google-Extended, Bingbot, Applebot...), llms.txt, the sitemap, and the homepage's noindex/canonical/body-text signals. Returns a 0-100 score and ranked fixes.
aeo_page_audit Read-only. Answer-readiness of one page: answer-first paragraph, question headings, FAQ, structured data, specifics, freshness, citations, scannability, plus a JSON-LD audit (required/recommended fields per type) and crawler directives. Returns scores, extractable answer blocks, and missing questions.
aeo_llms_txt Read-only. Validate a site's /llms.txt (llmstxt.org format), or build one: pass pages [{url,title,description,section}] with title and summary and it returns a ready file that passes validation.
aeo_schema_generate Pure. Generate valid JSON-LD for a page: kind = faq (qas [[q,a]...]), software (name,url,description,price), org (name,url,logo,same_as) or breadcrumbs (trail [[name,url]...]). Returns the object, its own audit, and a ready <script> tag.
aeo_visibility_record Record an AI share-of-answer panel. YOU (the calling agent) ask each engine the prompts and pass the answers here [{engine,prompt,text,citations}]; AdRails scores mentions, rank vs competitors, citations and sentiment, stores the run, and returns the score plus the change since the last run.
aeo_indexnow Tell Bing, Yandex, Seznam and Naver (IndexNow) that URLs changed. Checks the key file at https://host/.txt first. submit=false (default) only validates. Optionally pass sitemap_since (ISO date) to send every sitemap URL modified since then.
aeo_ai_traffic Read-only. Measure AI-driven traffic from a local web-server log (nginx combined or JSON lines): referrals from ChatGPT, Perplexity, Claude, Gemini and Copilot with landing pages, and AI crawler fetches split into verified / unverified / spoofed (by the providers' published IP ranges and scanner paths).
aeo_content_gaps Read-only. The ads-to-answers bridge: turn the campaign's real paid search terms into the questions people ask, check which of your pages already answer them, and return content briefs for the biggest gaps (facts only from site_facts, never invented).

Hardening applied to every tool (adsops/enterprise_tools.py:harden): role checks (rbac, off until enabled, then deny-by-default), an approval gate on commits (approvals.mode: off | exposure | all; HMAC-signed, expiring tokens; secret from env ADRAILS_APPROVAL_SECRET, 32+ chars), and a SHA-256 hash-chained audit log of every mutating call, refused ones included (audit_chain, default ~/.adsops/audit-chain.jsonl). Monitors deliver to the webhook URL in the env var named by alerts.webhook_env. Nothing here adds spending authority: account changes still go committed state file → adsops_plan → adsops_apply.

New CLI: adsops-mcp init --dir DIR --customer-id ID --campaign-id N --sa KEY.json scaffolds a campaign with a safe policy (caps = today's budget, commits off, enabling forbidden) and makes the first git commit; adsops-mcp --config DIR/config.json doctor reports what's missing, with a fix for each failed check.

Optional per-campaign config for the new tools: negatives (protect, out_of_area, competitor_brands, home_state, llm_command) and landing (towns); top-level intel_config points at your AdRails Intel tenant file (see adsops/intel/README.md).

The policy file

One policy file per campaign, referenced by policy_file in the config. AdRails only ever reads it: no tool writes caps, and adsops_set refuses guards and allow_enable outright. If the state file also carries caps they are ignored — the policy file always wins, and adsops_status says so.

{
  "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
}
Field Meaning
customer_id Account the campaign lives in; compared with the state file after stripping dashes. A mismatch is refused.
campaign_id The one campaign this policy governs; must match the state file exactly.
guards.max_daily_budget_usd Required. Upper bound of the daily budget, and the budget ceiling checked at plan time.
guards.min_daily_budget_usd Optional. Lower bound of the daily budget; must not exceed the maximum.
guards.max_end_date Required, YYYY-MM-DD. Latest end date any plan may set.
guards.lifetime_spend_pause_usd Required. Lifetime spend at which the guard issues a pause.
guards.daily_spend_pause_usd Required. Today's spend at which the guard issues a pause.
guards.max_ops_per_run Required integer. Most operations one run may emit; more is refused.
allow_enable Default false. Whether a plan may ever set the campaign to ENABLED.
max_guard_age_min Default null (check off). When set, any change that adds spend exposure is refused unless the guard heartbeat is younger than this.
require_plan_id Default false. When true, apply/commit and adsops_set with apply=true must quote a plan_id.
plan_ttl_s Default 900, range 60–86400. How long an issued plan_id stays usable; each one is consumed once.

A missing or malformed field is an error that names the field, not a silent default.

Desired-state file

One JSON file per campaign, referenced by state_file. It says what the campaign should look like; the server computes the diff.

{
  "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
  }
}
Field Meaning
customer_id Account the campaign lives in; dashes are stripped before use.
campaign_id / campaign_name The one campaign this file owns. Both must match live state or the run aborts.
status Desired status, ENABLED or PAUSED. ENABLED additionally requires allow_enable in the policy.
end_date Desired end date, YYYY-MM-DD, bounded by guards.max_end_date and not in the past.
daily_budget_usd Desired daily budget, bounded by the min/max guard band.
negatives_add Append-only list of {text, match_type}; match type is BROAD, PHRASE or EXACT. Nothing here removes a keyword.
guards Read only when the campaign has no policy_file (legacy mode). With a policy file configured, these are ignored.

Keep these files in git. That is what makes "reviewed desired state" real: git diff is the change review, and require_clean_git makes the server refuse to act on uncommitted edits.

Works with Google's official google-ads-mcp

Run both servers side by side in the same MCP client. Google's server answers ad-hoc GAQL exploration and never writes; AdRails is the only write path. The agent reads with the official server, proposes a change to a desired-state or policy file, and applies it through adsops_plan / adsops_apply — with caps, a validate pass, an account lock, and an audit line in between. Both speak JSON-RPC over stdio, so one .mcp.json entry each is the whole setup.

License

Apache-2.0.

Metadata

Release files for adrails 0.4.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for adrails 0.4.1
File Size Uploaded Provenance Actions
adrails-0.4.1.tar.gz 347.7 kB With provenance Details for adrails-0.4.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for adrails 0.4.1
File Interpreter ABI Platform Actions
adrails-0.4.1-py3-none-any.whl Python 3 none any Details for adrails-0.4.1-py3-none-any.whl

Total release size: 735.1 kB

Release files / adrails-0.4.1.tar.gz

Download URL adrails-0.4.1.tar.gz
Size 347.7 kB
Tags Source
SHA-256 checksum
How to use checksums
31206030b6ee59d46b36f7a912b77bb46bcd1ed45a08b0846d79f6b19cb09620
BLAKE2b-256 checksum
How to use checksums
485193e4d296a52716de0a98c0faba7410666cf3f8c6000ce1c2b5dbb63acab1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Release files / adrails-0.4.1-py3-none-any.whl

Download URL adrails-0.4.1-py3-none-any.whl
Size 387.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bbdc2db446145944d17a287d4b0a7748f5f5af83c5cc7a040b61249042f0a245
BLAKE2b-256 checksum
How to use checksums
a10b0931a4bb3d993bafa7f23f17287a25619ae1320787e5f16fa4f7684b54dc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Security for adrails 0.4.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for adrails-0.4.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page