adsmith

Let Claude actually run your Google Ads — with a diff, a dry-run, and an undo before anything touches your budget.

A Google Ads MCP server that does more than read. It finds your wasted spend, your budget-capped winners, and your weak ad copy — then proposes the fix as a reviewable diff that you approve before a single cent moves.

Google's official Google Ads MCP server is read-only: three tools, no mutations. adsmith is the other half — the part that changes things, wrapped in the safety machinery that makes letting an LLM near an ad budget a reasonable idea.

Try it in 30 seconds — no Google account needed

uvx adsmith --demo

That's it. No OAuth, no developer token, no waiting on Google's approval queue. --demo boots a synthetic ad account with realistically messy data, and every tool works against it, including proposing, applying, and rolling back changes.

Wire it into Claude Code:

claude mcp add adsmith -- uvx adsmith --demo

Then ask: "where am I wasting money?"

> where am I wasting money?

  Pulling the search-terms report for Northwind Outdoor Gear...

  $6,274.92 of your $14,525 spend over the last 30 days went to search terms
  that produced zero conversions — about 43%. The pattern is clear:

  | search term                    | 30-day cost | campaign               |
  |--------------------------------|-------------|------------------------|
  | free hiking boots              |     $261.98 | Search - Hiking Boots  |
  | hiking boots repair near me    |     $238.70 | Search - Hiking Boots  |
  | northwind outdoor gear careers |     $231.27 | Brand - Northwind      |
  | how to clean hiking boots      |     $215.41 | Search - Hiking Boots  |
  | used camping gear cheap        |     $191.82 | Search - Generic Outdoor |

  Three intent groups worth blocking: job seekers, repair/rental, and
  free-seekers. Want me to propose negatives?

> yes

  Change-set cs_1a5956d1 (pending) on customer 1234567890
  Rationale: Non-commercial intent

    1. Negative keyword on Search - Generic Outdoor: + keyword=jobs
    2. Negative keyword on Search - Generic Outdoor: + keyword=rental
    3. Negative keyword on Search - Generic Outdoor: + keyword=diy
    4. Negative keyword on Search - Generic Outdoor: + keyword=wikipedia
    5. Negative keyword on Search - Generic Outdoor: + keyword=donation

  Estimated daily spend decrease: 19.92
  Estimated 30-day impact: 597.60

  Expires: 2026-08-07T18:06:21+00:00
  To apply: apply_changeset(changeset_id='cs_1a5956d1', confirm=True)

  Nothing has been applied. Note I left "careers" alone — that spend is on your
  brand campaign, which your guardrails protect.

Nothing was applied. That's the point.

Safety, up front

The honest first reaction to "AI edits my ad account" is no. So here is exactly what stops it going wrong.

Every mutation takes the same path. There is no other route to the API:

propose_*  →  guardrails  →  validate_only dry-run  →  apply_changeset(confirm=True)
                   ↓                    ↓
              BLOCK is final     Google validates without committing

Guardrails live in a file on disk, outside the model's reach. No tool can relax one. A BLOCK is terminal — the assistant can't argue past it, because the check is Python reading YAML, not a suggestion in a prompt.

budgets:
  max_increase_pct_per_day: 20        # no 10x raises from a stray decimal
  max_decrease_pct_per_day: 30
  account_daily_spend_ceiling: null   # set this before automating anything

bids:
  max_target_cpa_change_pct: 15       # big swings reset Smart Bidding's learning

pausing:
  never_pause_if_conversions_last_30d: 5   # conversions lag; "dead" often isn't
  max_keywords_paused_per_changeset: 50
  allow_pausing_campaigns: false

protected:
  campaign_ids: []
  campaign_name_patterns: ["*Brand*"] # brand campaigns are cheap and high-ROAS;
                                      # "optimizing" them is nearly always a loss

Ask for something out of bounds and you get this, not a workaround:

Guardrails:
  - [BLOCK] budgets.max_increase_pct_per_day (change 1): Raising the budget for
    Search - Hiking Boots from 80.00 to 800.00 is +900.0%, above the 20% daily cap.

BLOCKED by guardrails — this change-set cannot be applied. The [BLOCK] entries
above are final.
These limits live in ~/.config/adsmith/guardrails.yaml. I cannot override them;
editing that file is the only way to change them.

The rest of the safety model:

• Approval is explicit. apply_changeset without confirm=True returns the diff and changes nothing.
• Dry run first. Every apply is validated through the API's validate_only mode before it commits.
• Undo. Change-sets carry pre-built inverse operations. Where something genuinely can't be reversed (creating an ad), it says so plainly instead of implying a clean undo.
• Proposals go stale. A change-set built on last week's numbers expires rather than applying against an account that has moved.
• Guardrails re-run at apply time, not just at propose time — so tightening the policy invalidates a proposal that was already sitting in the queue.
• Everything is logged. audit_history answers "what changed last Tuesday?" with every proposal, verdict, dry-run, application, and rollback.

Full detail in SECURITY.md.

Playbooks

Five slash commands, each a written analysis procedure rather than a black box. They're plain prose you can read and edit — including the statistical guardrails that stop an eager assistant acting on noise.

Tools

Running it unattended

adsmith scan does the analysis headlessly — point cron at it and the work happens while you sleep.

adsmith scan --demo              # digest of everything worth your attention
adsmith scan --propose           # ...and queue change-sets for the clear-cut fixes

9 finding(s), roughly 9,157.94 per 30 days at stake.

1. [WARNING] Search - Generic Outdoor: 2,384.42 on non-converting search terms
   85 search term(s) spent money over 30 days with no conversions.
   Queued: cs_ace79e8b (pending your approval)

3. [WARNING] Search - Camping Gear: CPA is +105% against target
   Actual CPA 61.41 vs target 30.00 over 61 conversions.

5. [WARNING] Search - Hiking Boots is capped and beating its target
   Losing 38% of impressions to budget on 80.00/day, at a CPA of 38.00
   against a 45.00 target.

It never applies anything — --propose queues change-sets in pending, and guardrails apply in full with nobody watching. The scan is deterministic Python, not an LLM: it costs nothing per run, gives identical output for identical input, and can't hallucinate a campaign ID. The judgement calls stay in the playbooks where you're present to read them.

Exit codes are cron-shaped (0 clean, 1 error, 2 findings), so adsmith scan || notify-me just works. Full setup, including systemd timers, in docs/SCHEDULING.md.

Read-only mode

adsmith --read-only

Unregisters every mutation tool, so the server physically cannot write — removal, not refusal. A good way to spend a first week on a real account.

Connecting a real account

--demo needs nothing. A real account needs three things from Google, and the developer token is the slow one — Google's review queue runs days to weeks, and a fresh token only works against test accounts until Basic access is approved.

Start the token application on day one, then keep using --demo while you wait. Full walkthrough in docs/SETUP.md.

pip install 'adsmith[live]'
adsmith auth                    # one-time OAuth; writes ~/.config/adsmith/credentials.json (0600)
adsmith init-config             # writes ~/.config/adsmith/guardrails.yaml — edit it
claude mcp add adsmith -- adsmith

Set account_daily_spend_ceiling in your guardrails before you do anything else.

How this differs from Google's official server

Both are open source and both are Python. They solve different halves.

Use theirs if you want a thin, official, read-only wrapper. Use adsmith if you want the thing to actually improve the account.

Contributing

You don't need a Google Ads account to contribute — the whole test suite runs against the demo backend. See CONTRIBUTING.md.

The one rule: nothing reaches the API except through a change-set. A tool that calls mutate directly won't be merged, however convenient.

Status

Alpha, and honest about it. 102 tests, CI on 3.12/3.13.

The safety layer is thoroughly covered. The live Google API path is tested against real protobuf types — message construction, enums, field masks, error translation — with the network stubbed, but it has never run against Google's actual servers. That's the part most likely to surprise you.

If you connect a real account: start with --read-only for a week, then tight guardrails and one small change. docs/SETUP.md §7 has the round trip worth doing first.

Licence

MIT.