# AdRails

> AdRails is an open-source MCP server that lets AI agents operate Google Ads inside caps you set, on your own machine, with your own keys.

AdRails is a local MCP server (JSON-RPC 2.0 over stdio) for Google Ads. It is Apache-2.0 and
free to run. The Python package and module are named `adsops` — that is what you install and
run (`adsops-mcp`, or `python3 -m adsops`).

An agent may read campaigns, status and search terms as often as it likes. Every write must
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.

## Tools

- `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, cap source, and the guard heartbeat's age.
- `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; returns the operations, exposure increases, and a single-use `plan_id` with its expiry.
- `adsops_apply` — Validate-only unless `commit=true`; a commit needs a clean git-tracked state file, a fresh guard heartbeat when exposure increases, and the `plan_id` when policy requires it.
- `adsops_set` — Proposes a budget / status / end-date / negatives change with a short `reason`, checks it against policy caps, writes the state file and commits it to git; `dry_run=true` returns a `plan_id`.
- `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.
- `adsops_usage` — Metering summary for the tenant: calls, errors, units, ops and median latency per tool.

## The rails

The rails are enforced by the executor in code, not by prompts. Each is covered by the test suite.

1. Caps in a policy file that no AdRails tool can write: max daily budget, end date, daily and lifetime pause thresholds, ops per run.
2. Single-use plan IDs: a commit must quote the exact plan it was shown; changed, reused or expired plans are refused.
3. Fail closed when nobody's watching: budget raises, re-enables and end-date extensions are blocked while the guard heartbeat is stale.
4. Pause-only spend guard: the scheduled guard pauses on threshold breach, and can never enable or raise anything.
5. Validate before every commit: Google checks the identical payload in validate-only mode first; nothing lands if that fails.
6. Reconcile, never blind-retry: if Google times out mid-commit, AdRails re-reads the account and reports what actually landed.
7. Every change has a reason: agent changes are committed to git with their stated reason, and every call is metered and audited.
8. Protected terms: listed keywords that pay the bills cannot be blocked by a negative keyword.

## Limits

AdRails reduces risk. It does not remove it. You run it at your own risk; you own your account
and your spend.

- 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 your average daily budget on a given day. A daily budget is an average, not a maximum, and reporting is delayed by minutes to hours.
- The guard only acts when it is scheduled and the machine is awake. While the machine sleeps no checks run, spend keeps moving, and the heartbeat goes stale. A chat-session MCP process is not a monitor.
- Local tools can be bypassed by an agent with shell access as the same OS user: it can edit files or call Google directly. Sandbox the agent or run the executor as its own user.
- Wrong negative keywords can suppress good traffic, and negatives are append-only here.

## Pricing

- The executor is free forever, Apache-2.0. No subscriptions, no seats, no account with AdRails.
- Optional services are paid per call in sats over Lightning (L402 first), coming soon: an independent AI second opinion on a plan before it commits, pause alerts to Telegram/Slack/SMS, and audit-log anchoring to Bitcoin.
- Optional services never touch your Google credentials and never proxy Google calls.

## Links

- [Home](https://adrails.dev/): overview, hero, quickstart entry point
- [How it works](https://adrails.dev/#how): plan, prove, commit
- [The rails](https://adrails.dev/#rails): all eight rails
- [Limits](https://adrails.dev/#honest): where the edges are
- [Pricing](https://adrails.dev/#pricing): free core, sats per call
- [Quickstart](https://adrails.dev/#start): config, policy file, MCP registration

## Source
- GitHub: https://github.com/antonioac1/adrails (Apache-2.0)