mcp-google-ads-safe 2.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- mcp_google_ads_safe-2.0.0/CHANGELOG.md +155 -0
- mcp_google_ads_safe-2.0.0/CONTRIBUTING.md +44 -0
- mcp_google_ads_safe-2.0.0/LICENSE +21 -0
- mcp_google_ads_safe-2.0.0/MANIFEST.in +5 -0
- mcp_google_ads_safe-2.0.0/PKG-INFO +189 -0
- mcp_google_ads_safe-2.0.0/README.md +156 -0
- mcp_google_ads_safe-2.0.0/SECURITY.md +35 -0
- mcp_google_ads_safe-2.0.0/advertiser.example.yaml +53 -0
- mcp_google_ads_safe-2.0.0/docs/configuration.md +97 -0
- mcp_google_ads_safe-2.0.0/docs/google-auth-transition.md +17 -0
- mcp_google_ads_safe-2.0.0/docs/keyword-discovery.md +69 -0
- mcp_google_ads_safe-2.0.0/docs/keyword-forecasts.md +55 -0
- mcp_google_ads_safe-2.0.0/docs/m1-verification.md +161 -0
- mcp_google_ads_safe-2.0.0/docs/m2-audience-targeting.md +37 -0
- mcp_google_ads_safe-2.0.0/docs/m2-callouts.md +33 -0
- mcp_google_ads_safe-2.0.0/docs/m2-conversion-creation.md +58 -0
- mcp_google_ads_safe-2.0.0/docs/m2-conversion-primary-status.md +34 -0
- mcp_google_ads_safe-2.0.0/docs/m2-creation.md +107 -0
- mcp_google_ads_safe-2.0.0/docs/m2-custom-audience.md +49 -0
- mcp_google_ads_safe-2.0.0/docs/m2-image-upload.md +48 -0
- mcp_google_ads_safe-2.0.0/docs/m2-pmax-creation.md +98 -0
- mcp_google_ads_safe-2.0.0/docs/m2-recommendation-apply.md +30 -0
- mcp_google_ads_safe-2.0.0/docs/m2-recommendation-dismiss.md +38 -0
- mcp_google_ads_safe-2.0.0/docs/m2-remove-extension.md +37 -0
- mcp_google_ads_safe-2.0.0/docs/m2-responsive-search-ad.md +69 -0
- mcp_google_ads_safe-2.0.0/docs/m2-sitelinks.md +40 -0
- mcp_google_ads_safe-2.0.0/docs/m2-structured-snippets.md +38 -0
- mcp_google_ads_safe-2.0.0/docs/m2-text-upload.md +43 -0
- mcp_google_ads_safe-2.0.0/docs/m2-verification.md +70 -0
- mcp_google_ads_safe-2.0.0/docs/m3-asset-group-add-assets.md +56 -0
- mcp_google_ads_safe-2.0.0/docs/m3-asset-group-creation.md +42 -0
- mcp_google_ads_safe-2.0.0/docs/m3-asset-group-remove-asset.md +38 -0
- mcp_google_ads_safe-2.0.0/docs/m3-asset-group-update.md +30 -0
- mcp_google_ads_safe-2.0.0/docs/m3-demand-gen-ad.md +35 -0
- mcp_google_ads_safe-2.0.0/docs/m3-demand-gen-campaign.md +60 -0
- mcp_google_ads_safe-2.0.0/docs/m3-listing-group-filter.md +35 -0
- mcp_google_ads_safe-2.0.0/docs/m3-shared-negative-sets.md +109 -0
- mcp_google_ads_safe-2.0.0/docs/offline-capability-matrix.md +193 -0
- mcp_google_ads_safe-2.0.0/docs/policy-issues.md +29 -0
- mcp_google_ads_safe-2.0.0/docs/release-readiness.md +57 -0
- mcp_google_ads_safe-2.0.0/docs/setup.md +140 -0
- mcp_google_ads_safe-2.0.0/docs/tool-reference.md +271 -0
- mcp_google_ads_safe-2.0.0/docs/troubleshooting.md +70 -0
- mcp_google_ads_safe-2.0.0/docs/validation-readiness.md +98 -0
- mcp_google_ads_safe-2.0.0/mcp_google_ads_safe/__init__.py +0 -0
- mcp_google_ads_safe-2.0.0/mcp_google_ads_safe/app.py +270 -0
- mcp_google_ads_safe-2.0.0/mcp_google_ads_safe/audit.py +35 -0
- mcp_google_ads_safe-2.0.0/mcp_google_ads_safe/auth_helper.py +349 -0
- mcp_google_ads_safe-2.0.0/mcp_google_ads_safe/client.py +7202 -0
- mcp_google_ads_safe-2.0.0/mcp_google_ads_safe/rails.py +3694 -0
- mcp_google_ads_safe-2.0.0/mcp_google_ads_safe/server.py +25 -0
- mcp_google_ads_safe-2.0.0/mcp_google_ads_safe/settings.py +296 -0
- mcp_google_ads_safe-2.0.0/mcp_google_ads_safe/setup_wizard.py +152 -0
- mcp_google_ads_safe-2.0.0/mcp_google_ads_safe/tools.py +1044 -0
- mcp_google_ads_safe-2.0.0/mcp_google_ads_safe/undo.py +285 -0
- mcp_google_ads_safe-2.0.0/mcp_google_ads_safe.egg-info/PKG-INFO +189 -0
- mcp_google_ads_safe-2.0.0/mcp_google_ads_safe.egg-info/SOURCES.txt +118 -0
- mcp_google_ads_safe-2.0.0/mcp_google_ads_safe.egg-info/dependency_links.txt +1 -0
- mcp_google_ads_safe-2.0.0/mcp_google_ads_safe.egg-info/entry_points.txt +2 -0
- mcp_google_ads_safe-2.0.0/mcp_google_ads_safe.egg-info/requires.txt +11 -0
- mcp_google_ads_safe-2.0.0/mcp_google_ads_safe.egg-info/top_level.txt +1 -0
- mcp_google_ads_safe-2.0.0/pyproject.toml +55 -0
- mcp_google_ads_safe-2.0.0/setup.cfg +4 -0
- mcp_google_ads_safe-2.0.0/tests/__init__.py +0 -0
- mcp_google_ads_safe-2.0.0/tests/conftest.py +293 -0
- mcp_google_ads_safe-2.0.0/tests/test_account_rules.py +259 -0
- mcp_google_ads_safe-2.0.0/tests/test_agency_scope.py +453 -0
- mcp_google_ads_safe-2.0.0/tests/test_audience_targeting.py +336 -0
- mcp_google_ads_safe-2.0.0/tests/test_audit.py +100 -0
- mcp_google_ads_safe-2.0.0/tests/test_auth_helper.py +478 -0
- mcp_google_ads_safe-2.0.0/tests/test_bidding.py +98 -0
- mcp_google_ads_safe-2.0.0/tests/test_bootstrap_smoke.py +8 -0
- mcp_google_ads_safe-2.0.0/tests/test_callouts.py +298 -0
- mcp_google_ads_safe-2.0.0/tests/test_client.py +61 -0
- mcp_google_ads_safe-2.0.0/tests/test_client_api.py +1051 -0
- mcp_google_ads_safe-2.0.0/tests/test_conversion_creation.py +930 -0
- mcp_google_ads_safe-2.0.0/tests/test_conversion_primary_status.py +346 -0
- mcp_google_ads_safe-2.0.0/tests/test_creation_reads.py +146 -0
- mcp_google_ads_safe-2.0.0/tests/test_creation_tools.py +458 -0
- mcp_google_ads_safe-2.0.0/tests/test_criteria_tools.py +549 -0
- mcp_google_ads_safe-2.0.0/tests/test_custom_audience.py +329 -0
- mcp_google_ads_safe-2.0.0/tests/test_demand_gen_ad.py +745 -0
- mcp_google_ads_safe-2.0.0/tests/test_demand_gen_campaign.py +675 -0
- mcp_google_ads_safe-2.0.0/tests/test_describe_fields.py +101 -0
- mcp_google_ads_safe-2.0.0/tests/test_final_fixes.py +195 -0
- mcp_google_ads_safe-2.0.0/tests/test_keyword_discovery.py +252 -0
- mcp_google_ads_safe-2.0.0/tests/test_keyword_forecasts.py +200 -0
- mcp_google_ads_safe-2.0.0/tests/test_listing_group_filter.py +805 -0
- mcp_google_ads_safe-2.0.0/tests/test_m2_reads.py +174 -0
- mcp_google_ads_safe-2.0.0/tests/test_mcp_smoke.py +162 -0
- mcp_google_ads_safe-2.0.0/tests/test_mutation_actions.py +151 -0
- mcp_google_ads_safe-2.0.0/tests/test_no_google_imports_outside_client.py +66 -0
- mcp_google_ads_safe-2.0.0/tests/test_pmax_asset_group_asset_remove.py +543 -0
- mcp_google_ads_safe-2.0.0/tests/test_pmax_asset_group_assets.py +806 -0
- mcp_google_ads_safe-2.0.0/tests/test_pmax_asset_group_creation.py +473 -0
- mcp_google_ads_safe-2.0.0/tests/test_pmax_asset_group_update.py +572 -0
- mcp_google_ads_safe-2.0.0/tests/test_pmax_creation.py +553 -0
- mcp_google_ads_safe-2.0.0/tests/test_policy_issues.py +109 -0
- mcp_google_ads_safe-2.0.0/tests/test_portfolio_creation.py +332 -0
- mcp_google_ads_safe-2.0.0/tests/test_protocol_errors.py +171 -0
- mcp_google_ads_safe-2.0.0/tests/test_rails.py +431 -0
- mcp_google_ads_safe-2.0.0/tests/test_read_tools.py +99 -0
- mcp_google_ads_safe-2.0.0/tests/test_readable_reports.py +229 -0
- mcp_google_ads_safe-2.0.0/tests/test_recommendation_apply.py +409 -0
- mcp_google_ads_safe-2.0.0/tests/test_recommendation_dismiss.py +271 -0
- mcp_google_ads_safe-2.0.0/tests/test_remove_entity.py +472 -0
- mcp_google_ads_safe-2.0.0/tests/test_remove_extension.py +424 -0
- mcp_google_ads_safe-2.0.0/tests/test_responsive_search_ad.py +283 -0
- mcp_google_ads_safe-2.0.0/tests/test_review_2026_09_14.py +235 -0
- mcp_google_ads_safe-2.0.0/tests/test_server.py +123 -0
- mcp_google_ads_safe-2.0.0/tests/test_settings.py +224 -0
- mcp_google_ads_safe-2.0.0/tests/test_setup_wizard.py +191 -0
- mcp_google_ads_safe-2.0.0/tests/test_shared_negative_sets.py +1198 -0
- mcp_google_ads_safe-2.0.0/tests/test_sitelinks.py +277 -0
- mcp_google_ads_safe-2.0.0/tests/test_status_tools.py +204 -0
- mcp_google_ads_safe-2.0.0/tests/test_structured_snippets.py +320 -0
- mcp_google_ads_safe-2.0.0/tests/test_undo.py +252 -0
- mcp_google_ads_safe-2.0.0/tests/test_update_tools.py +436 -0
- mcp_google_ads_safe-2.0.0/tests/test_upload_image_asset.py +334 -0
- mcp_google_ads_safe-2.0.0/tests/test_upload_text_asset.py +306 -0
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 2.0.0 - 2026-11-19
|
|
4
|
+
|
|
5
|
+
Agency-ready and built for marketers. Breaking changes are marked.
|
|
6
|
+
|
|
7
|
+
Agency use:
|
|
8
|
+
- New tool `find_accounts`: search the accounts under the login manager by name. One
|
|
9
|
+
request, no metrics, every level of the manager account.
|
|
10
|
+
- New tools `use_account` and `current_account`: pick the account reports use when none is
|
|
11
|
+
named. Reports only. A change must name its `customer_id` every time and is refused
|
|
12
|
+
(`ACCOUNT_REQUIRED`) if it does not while a pick is active.
|
|
13
|
+
- New opt-in `GOOGLE_ADS_READ_SCOPE=manager`: reports on any enabled, visible account under
|
|
14
|
+
the login manager without listing it. Changes stay limited to
|
|
15
|
+
`GOOGLE_ADS_WRITE_CUSTOMER_IDS` in every scope, and every change looks its account up
|
|
16
|
+
fresh.
|
|
17
|
+
- Startup and `health_check` prove the listed accounts with one request instead of walking
|
|
18
|
+
the manager tree. The depth-3 / 500-account limit and `ANCESTRY_TRUNCATED` are gone.
|
|
19
|
+
`list_accounts` is one request instead of one per account.
|
|
20
|
+
- `advertiser.yaml` takes an optional `accounts:` map: each account can have its own
|
|
21
|
+
`advertiser_domain`, `blocked_terms` (added to the top-level list), `keyword_research`
|
|
22
|
+
and spend caps (`max_daily_budget`, `max_cpc`, `max_target_cpa`, in that account's own
|
|
23
|
+
currency). See `advertiser.example.yaml`. With per-account rules configured, a step that
|
|
24
|
+
does not say which account it is for is refused (`NO_ACCOUNT_CONTEXT`). Per-account caps
|
|
25
|
+
replace the environment caps for that account and are not held under them; an account
|
|
26
|
+
that sets any cap must set `max_daily_budget` and `max_cpc` together, and startup prints
|
|
27
|
+
each account that has its own caps.
|
|
28
|
+
- Every draft names its account and the spend caps that apply, beside the preview.
|
|
29
|
+
|
|
30
|
+
Reports:
|
|
31
|
+
- Breaking: reports return readable rows by default: status and type names instead of
|
|
32
|
+
integers, only the fields selected, counts as numbers, and money both in micros and in
|
|
33
|
+
whole currency units (`cost`, `*_amount`). `run_gaql(raw=True)` returns the old rows.
|
|
34
|
+
- Breaking: every report answer carries `account` (which account, how it was chosen) and
|
|
35
|
+
`provenance` (account name, currency, time zone, the resolved dates, the exact query,
|
|
36
|
+
rows returned out of total, whether it was cut, and a conversions note).
|
|
37
|
+
- The five performance reports take `limit` (default 100, maximum 1,000). `get_search_terms`
|
|
38
|
+
no longer has a fixed 200-row cap. The default period is still the last 30 days, now sent
|
|
39
|
+
as explicit dates so the answer states them.
|
|
40
|
+
- Breaking: giving only one of `date_range_start` / `date_range_end` is refused (`BAD_DATE`)
|
|
41
|
+
instead of silently using the default period.
|
|
42
|
+
- New tool `describe_fields`: the common report resources in plain words, and for any
|
|
43
|
+
resource its selectable fields, metrics and segments from Google's field catalog.
|
|
44
|
+
- `run_gaql` documents eight recipes, each run read-only against a live account.
|
|
45
|
+
- Breaking: `health_check` returns `login_manager`, `read_scope` and `reachable_accounts`
|
|
46
|
+
(enabled, visible client accounts); in manager scope a count replaces the `accounts` list.
|
|
47
|
+
|
|
48
|
+
Setup and packaging:
|
|
49
|
+
- `mcp-google-ads-safe setup` and `mcp-google-ads-safe reauth`: guided sign-in in three
|
|
50
|
+
questions, then a ready-to-paste read-only client configuration. The bare command still
|
|
51
|
+
serves.
|
|
52
|
+
- One-line run: `uvx --from git+https://github.com/wvuhskr/mcp-google-ads-safe mcp-google-ads-safe`.
|
|
53
|
+
- `mcp>=1.30.0` (CVE-2026-59951, CVE-2026-116684/5/6), `Pillow>=13.0.0` (CVE-2026-128066,
|
|
54
|
+
CVE-2026-128067), `google-ads` 32 through 35 (all ship API v25). CI adds `pip-audit` and a
|
|
55
|
+
job on the oldest supported `mcp`. PyPI trusted-publishing workflow added.
|
|
56
|
+
- README rewritten for marketers. 4,001 tests. Tool count 64.
|
|
57
|
+
|
|
58
|
+
Not changed: creating a conversion action still reads every account under the manager
|
|
59
|
+
before it will draft, so it stays slow on very large manager accounts.
|
|
60
|
+
|
|
61
|
+
## 1.1.0 - 2026-09-14
|
|
62
|
+
|
|
63
|
+
- New tool `undo_change(draft_id)`: drafts the reverse of an applied change from the audit
|
|
64
|
+
log. Rides the normal draft/confirm rails and never dispatches on its own. Reversible:
|
|
65
|
+
campaign and ad-group updates, pause/enable, keyword and negative additions or removals,
|
|
66
|
+
keyword bids, schedules; enabled creations are paused. Removals and uploads are reported
|
|
67
|
+
as permanent. See the [tool reference](docs/tool-reference.md#undo).
|
|
68
|
+
- Combined `update_campaign` previews record `current_daily_budget` so a budget change made
|
|
69
|
+
alongside other fields can be undone.
|
|
70
|
+
- 3,853 tests. Tool count 60.
|
|
71
|
+
|
|
72
|
+
## 1.0.1 - 2026-09-14
|
|
73
|
+
|
|
74
|
+
First public release. A same-day public-readiness review found two High and seven Medium
|
|
75
|
+
issues; all are fixed here. Breaking for nobody: every new control defaults to the old
|
|
76
|
+
behavior or to "off".
|
|
77
|
+
|
|
78
|
+
Safety:
|
|
79
|
+
- Clearing target CPA or target ROAS on a Performance Max campaign is refused
|
|
80
|
+
(`PMAX_TARGET_CLEAR`). The daily budget still caps spend; this protects cost per result.
|
|
81
|
+
Raise the target in steps instead. A product choice, not a Google requirement.
|
|
82
|
+
- The draft store is serialized with a lock, so two concurrent confirms cannot both dispatch.
|
|
83
|
+
- Only documented sign-in keys are read from the credential YAML; any other key (including
|
|
84
|
+
`logging`) stops startup.
|
|
85
|
+
- Transport-class failures from the mutate RPC (Unavailable, DeadlineExceeded, Internal,
|
|
86
|
+
Unknown, Aborted, Cancelled, ResourceExhausted) are audited as `unknown`. Definite
|
|
87
|
+
server-side rejections (InvalidArgument, PermissionDenied, NotFound, Unauthenticated and
|
|
88
|
+
similar) stay `error`, since Google answered and saved nothing.
|
|
89
|
+
- Refused confirms for unknown, expired or tampered drafts are audited (`UNKNOWN_DRAFT`,
|
|
90
|
+
`DRAFT_EXPIRED`, `PLAN_TAMPERED`).
|
|
91
|
+
- A write that landed but failed read-back is audited as `apply_unverified`, not `error`.
|
|
92
|
+
- New `GOOGLE_ADS_MAX_TARGET_CPA` cap, separate from `GOOGLE_ADS_MAX_CPC` (falls back to
|
|
93
|
+
it when unset).
|
|
94
|
+
- New `GOOGLE_ADS_ALLOW_REMOVE_ENTITY` opt-in (default false) for permanent removal,
|
|
95
|
+
checked at draft and again at confirm.
|
|
96
|
+
- One generic input guard rejects string arguments that would coerce to JSON null, list
|
|
97
|
+
or object, for every tool.
|
|
98
|
+
- Report dates must be `YYYY-MM-DD`; geo-target search escapes backslashes.
|
|
99
|
+
|
|
100
|
+
Project:
|
|
101
|
+
- README rewritten for a public audience with a comparison against other Google Ads MCP
|
|
102
|
+
servers. SECURITY.md routes reports through GitHub private vulnerability reporting.
|
|
103
|
+
- CI: ruff, the full test suite and a high-severity Bandit scan on Ubuntu and macOS across
|
|
104
|
+
Python 3.12, 3.13 and 3.14. Dependabot for pip and GitHub Actions.
|
|
105
|
+
- The three extension-state readers collapsed into one; no behavior change.
|
|
106
|
+
- 3,830 tests (was 3,807).
|
|
107
|
+
|
|
108
|
+
## 1.0.0 - 2026-09-11
|
|
109
|
+
|
|
110
|
+
Stable source release, reviewed privately before the public 1.0.1. The operation inventory
|
|
111
|
+
retains explicit distinctions between current reads, historical write evidence and
|
|
112
|
+
synthetic tests.
|
|
113
|
+
|
|
114
|
+
- Added bounded read and draft/confirm operations for Search, Performance Max,
|
|
115
|
+
Demand Gen, assets, audiences, conversions, recommendations, keyword research and
|
|
116
|
+
shared negative sets. See the [operation inventory](docs/offline-capability-matrix.md)
|
|
117
|
+
for branch-specific scope and evidence.
|
|
118
|
+
- Documented future approval and independent saved-state checks in
|
|
119
|
+
[validation readiness](docs/validation-readiness.md). Offline synthetic evidence,
|
|
120
|
+
dated provider reads, exact-payload validation and applied/read-back evidence remain
|
|
121
|
+
separate; no blanket provider acceptance, serving or performance claim is made.
|
|
122
|
+
- Retired superseded test-account setup directions, clarified real startup preflight,
|
|
123
|
+
and recorded remaining [release gates](docs/release-readiness.md).
|
|
124
|
+
- Reorganized public onboarding around source installation, an existing private Google Ads
|
|
125
|
+
credential profile, a generic MCP client connection, a live read-only first check,
|
|
126
|
+
[configuration](docs/configuration.md), and [troubleshooting](docs/troubleshooting.md).
|
|
127
|
+
- Moved the complete capability and evidence ledger to the
|
|
128
|
+
[tool reference](docs/tool-reference.md) so the main README can lead with setup and safety.
|
|
129
|
+
- Required an explicit credential profile path through `GOOGLE_ADS_YAML` or the client
|
|
130
|
+
factory argument, removing the former implicit path.
|
|
131
|
+
- Adopted `google-ads>=32.0.0,<33` so service-account profiles can omit the retired
|
|
132
|
+
developer token, while retaining existing Desktop user profiles and all server account
|
|
133
|
+
and write guards. This is offline compatibility evidence, not a stable release claim.
|
|
134
|
+
- Recorded a September 10, 2026 bounded check in which one existing user-authorization profile
|
|
135
|
+
refreshed authorization and completed account discovery plus installed startup
|
|
136
|
+
prerequisites and health for one selected advertiser with writes disabled. This does
|
|
137
|
+
not prove first-time setup, recovery, an assistant connection, every provider operation,
|
|
138
|
+
or stable-release readiness.
|
|
139
|
+
|
|
140
|
+
Final artifact checks, exact source/history privacy clearance and publication controls
|
|
141
|
+
remain separate from the bounded validations listed below. Alternative setup paths and
|
|
142
|
+
mutation branches retain their documented evidence limits.
|
|
143
|
+
Existing private Alpha artifacts predate these documentation changes.
|
|
144
|
+
|
|
145
|
+
- Verified Desktop initial sign-in, explicit private-profile replacement and restarted
|
|
146
|
+
health check through an MCP client (OpenAI Codex) with writes disabled. Service-account provisioning and deliberately
|
|
147
|
+
revoked-token recovery remain unverified alternatives.
|
|
148
|
+
- Qualified fresh macOS Apple Silicon installations on Python 3.12.13, 3.13.14 and
|
|
149
|
+
3.14.6 with complete synthetic suites; retained exact dependency resolutions.
|
|
150
|
+
- Verified current account/report/entity/policy/configuration/recommendation reads
|
|
151
|
+
for one account. A direct query reconciled campaign counts and spend; negative
|
|
152
|
+
keywords exercised multiple pages. Search terms remain capped.
|
|
153
|
+
- Verified one keyword-discovery page and an unsaved campaign forecast; results are
|
|
154
|
+
provider estimates with explicit unavailable fields, not actual advertising outcomes.
|
|
155
|
+
- Included setup/reference documentation and this changelog in source distributions.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# Contributing
|
|
2
|
+
|
|
3
|
+
Thanks for helping improve Google Ads MCP Safe. Small, focused fixes, documentation improvements, and reproducible bug reports are welcome. Contributions are reviewed; submission does not guarantee acceptance or a response deadline.
|
|
4
|
+
|
|
5
|
+
## Before opening a report
|
|
6
|
+
|
|
7
|
+
Read the [README](README.md), [troubleshooting guide](docs/troubleshooting.md), and [tool reference](docs/tool-reference.md). Search existing issues for the same problem. Use a bug report for unexpected behavior or a feature request to describe a missing capability and its practical benefit.
|
|
8
|
+
|
|
9
|
+
Suspected security problems go through GitHub private vulnerability reporting as described in [SECURITY.md](SECURITY.md), never in a public issue, pull request or discussion.
|
|
10
|
+
|
|
11
|
+
Never upload sign-in profiles, tokens, keys, real account identifiers, customer information, advertising results, or raw provider responses. Use synthetic examples and remove private details from logs and screenshots.
|
|
12
|
+
|
|
13
|
+
## Local development
|
|
14
|
+
|
|
15
|
+
Use Python 3.12 or newer. The [README](README.md) describes the exact environments tested so far; do not assume all platforms are verified.
|
|
16
|
+
|
|
17
|
+
In the macOS Terminal app, from your copy of this project's root folder, create an isolated environment and install the development tools:
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
python3.12 -m venv .venv
|
|
21
|
+
source .venv/bin/activate
|
|
22
|
+
python -m pip install -e '.[dev]'
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Installation can download dependencies. No Google credentials are needed for the offline test suite. In the same Terminal window and project folder, run:
|
|
26
|
+
|
|
27
|
+
```sh
|
|
28
|
+
python -m pytest -q
|
|
29
|
+
python -m ruff check .
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
The tests use simulated provider calls and synthetic accounts. Some tests enable write settings inside those simulations to verify safeguards; this is not permission to enable writes against a real account. Preserve the test protections that block real provider construction and network access. Do not add tests that load real credentials or contact Google by default.
|
|
33
|
+
|
|
34
|
+
## Proposing a change
|
|
35
|
+
|
|
36
|
+
Open a pull request, a proposed set of changes for review, with the problem, resulting behavior, and verification results. Keep changes focused and explain any effect on account permissions, write safeguards, credential handling, or audit records. Update the relevant documentation when behavior changes. Include a regression test for a bug fix when it can meaningfully demonstrate the failure and correction.
|
|
37
|
+
|
|
38
|
+
Report the commands you ran and their actual results. Separate offline tests from any separately authorized live checks; simulations do not prove that Google accepted a request. A code contribution does not authorize live account changes, credential changes, or publication.
|
|
39
|
+
|
|
40
|
+
Only submit material you have the right to contribute. Contributions are provided under this project's [MIT license](LICENSE).
|
|
41
|
+
|
|
42
|
+
## Working together
|
|
43
|
+
|
|
44
|
+
Be respectful, critique the work rather than the person, and keep discussions relevant. Harassment, threats, discriminatory abuse, and sharing private information are not acceptable. Maintainers may remove disruptive content or restrict participation.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Alex Murtha
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: mcp-google-ads-safe
|
|
3
|
+
Version: 2.0.0
|
|
4
|
+
Summary: Safety-first MCP server for the Google Ads API: opt-in writes, two-phase draft/confirm, spend rails, Smart Bidding guards, audit log.
|
|
5
|
+
Author-email: Alex Murtha <wvuhskr@users.noreply.github.com>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/wvuhskr/mcp-google-ads-safe
|
|
8
|
+
Project-URL: Repository, https://github.com/wvuhskr/mcp-google-ads-safe
|
|
9
|
+
Project-URL: Issues, https://github.com/wvuhskr/mcp-google-ads-safe/issues
|
|
10
|
+
Project-URL: Changelog, https://github.com/wvuhskr/mcp-google-ads-safe/blob/main/CHANGELOG.md
|
|
11
|
+
Keywords: mcp,model-context-protocol,google-ads,advertising,paid-media,ppc,llm
|
|
12
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Environment :: Console
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
18
|
+
Classifier: Topic :: Office/Business :: Financial
|
|
19
|
+
Requires-Python: >=3.12
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
License-File: LICENSE
|
|
22
|
+
Requires-Dist: google-ads<36,>=32.0.0
|
|
23
|
+
Requires-Dist: mcp<3,>=1.30.0
|
|
24
|
+
Requires-Dist: pyyaml>=6.0.3
|
|
25
|
+
Requires-Dist: Pillow<14,>=13.0.0
|
|
26
|
+
Provides-Extra: dev
|
|
27
|
+
Requires-Dist: pytest>=8; extra == "dev"
|
|
28
|
+
Requires-Dist: pytest-cov>=5; extra == "dev"
|
|
29
|
+
Requires-Dist: ruff>=0.6; extra == "dev"
|
|
30
|
+
Requires-Dist: bandit>=1.9.4; extra == "dev"
|
|
31
|
+
Requires-Dist: pip-audit>=2.7; extra == "dev"
|
|
32
|
+
Dynamic: license-file
|
|
33
|
+
|
|
34
|
+
# Google Ads MCP Safe
|
|
35
|
+
|
|
36
|
+
A Google Ads MCP server that lets an AI assistant change your account, with the brakes built into the server instead of the prompt.
|
|
37
|
+
|
|
38
|
+
MCP (Model Context Protocol) is the standard that lets assistants like Claude, Codex, or Cursor call tools. Most Google Ads MCP servers are either read-only (Google's own is, on purpose) or hand the assistant raw write access and hope for the best. This one sits in the middle: 64 tools that cover research, reporting, and account changes across Search, Performance Max, and Demand Gen, where every change has to pass a set of checks the assistant cannot talk its way around.
|
|
39
|
+
|
|
40
|
+
Independent, third-party project. Not affiliated with, endorsed by, or maintained by Google. Uses Google Ads API v25. MIT licensed.
|
|
41
|
+
|
|
42
|
+
## Why another Google Ads MCP?
|
|
43
|
+
|
|
44
|
+
I manage paid media day to day. I wanted an assistant that could pull search terms, draft negatives, and adjust a target CPA on a Monday morning without me worrying that a misread instruction would triple a budget or un-pause a campaign I had killed for a reason. The write-capable servers I found had one or two safeguards each. None had the full set, and the ones that came closest had a single user.
|
|
45
|
+
|
|
46
|
+
So the design goal here is simple: the assistant proposes, the server decides whether that proposal is allowed, and nothing reaches Google until a second explicit call says go.
|
|
47
|
+
|
|
48
|
+
### How it compares
|
|
49
|
+
|
|
50
|
+
| | Google official server | Typical community write server | Google Ads MCP Safe |
|
|
51
|
+
| --- | --- | --- | --- |
|
|
52
|
+
| Reads (GAQL, reports, account discovery) | Yes | Yes | Yes, readable, row-limited, each naming its account and dates |
|
|
53
|
+
| Agency use (many client accounts under one manager) | Varies | Varies | Find by name, read any, change only listed ones, per-client rules and spend limits |
|
|
54
|
+
| Writes | No, by design | Yes | Yes, off by default |
|
|
55
|
+
| Per-account write allowlist | n/a | Rare | Yes. Reads can optionally cover a whole manager account; changes never do |
|
|
56
|
+
| Preview then separate confirm call | n/a | Some | Yes, every write |
|
|
57
|
+
| Daily budget, CPC, and target CPA ceilings | n/a | Some | Yes, three separate caps |
|
|
58
|
+
| Refuses to clear a Performance Max target (budget still caps spend; this protects cost per result) | n/a | Not found | Yes |
|
|
59
|
+
| Extra opt-in for shared or blast-radius resources | n/a | Not found | Yes, seven separate switches (shared budgets, portfolios, conversion goals, shared audiences, recommendations, shared negative lists, permanent removal) |
|
|
60
|
+
| New campaigns, ad groups, ads created PAUSED | n/a | Some | Yes, always |
|
|
61
|
+
| Local audit log | n/a | Some log applied writes | Logs drafts, refusals, applies, and unknown outcomes |
|
|
62
|
+
| Fresh state re-check at confirm time | n/a | Not found | Yes |
|
|
63
|
+
| Undo for applied changes | n/a | Not found | Yes, drafts the reverse from the audit log |
|
|
64
|
+
| Automated tests | Unknown | Usually few or none | 4,001 |
|
|
65
|
+
|
|
66
|
+
"Typical community write server" summarizes the open-source write-capable servers I could find on GitHub in September 2026. The best of them ship two or three of these gates. To my knowledge none combine all of them in a maintained project, but I have not audited every repo, and this table is a snapshot, not a scoreboard. The [Google official server](https://developers.google.com/google-ads/api/docs/developer-toolkit/mcp-server) is the right choice if you only need reads and want Google-maintained code.
|
|
67
|
+
|
|
68
|
+
## What you can ask
|
|
69
|
+
|
|
70
|
+
Once connected, talk to your assistant in plain words. It picks the tools.
|
|
71
|
+
|
|
72
|
+
- "Find the Smith Dental account and use it."
|
|
73
|
+
- "How did each campaign do in the last 30 days? Show spend, conversions and cost per conversion."
|
|
74
|
+
- "Which search terms spent money with no conversions last month?"
|
|
75
|
+
- "What share of search impressions are we losing to budget, by campaign?"
|
|
76
|
+
- "Do the same check for the next client on my list."
|
|
77
|
+
- "Draft a negative keyword list from those search terms." (a change: previewed first, applied only on a second explicit step, and only if you turned changes on)
|
|
78
|
+
|
|
79
|
+
Every report says which account it came from, its currency and time zone, the exact dates it covers, and whether it was cut short. Money is shown in whole currency units, statuses as words. The standard performance reports return 100 rows unless you ask for more (up to 1,000). Custom queries and account lookups return up to one page (10,000 rows) and say when more exist, so add a limit to those yourself.
|
|
80
|
+
|
|
81
|
+
## Quick start
|
|
82
|
+
|
|
83
|
+
You need Python 3.12 or newer, [uv](https://docs.astral.sh/uv/) (a small tool that runs Python programs without a manual install), a Google Cloud project with Google Ads API access (the [setup guide](docs/setup.md) explains how to get one), and access to the account or manager account you want to use.
|
|
84
|
+
|
|
85
|
+
1. In your terminal (on a Mac, the Terminal app), run the guided setup. It asks three plain questions, opens Google's sign-in page, and saves a private sign-in file:
|
|
86
|
+
|
|
87
|
+
```sh
|
|
88
|
+
uvx --from git+https://github.com/wvuhskr/mcp-google-ads-safe mcp-google-ads-safe setup
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
2. Paste the configuration it prints into your assistant (Claude Desktop or Claude Code; other MCP clients take the same values).
|
|
92
|
+
3. Quit and reopen the assistant.
|
|
93
|
+
4. Ask it: "run health_check, then find_accounts".
|
|
94
|
+
5. Ask it: "use the account named ..." and start asking questions.
|
|
95
|
+
|
|
96
|
+
That setup is read-only and can report on every enabled account under your manager account. Nothing can be changed until you turn changes on. The package is not on PyPI yet, so the command above installs from GitHub. A service account, or a manual setup with explicit account lists, is in the [setup guide](docs/setup.md). To sign in again later: the same command with `reauth` in place of `setup`.
|
|
97
|
+
|
|
98
|
+
### Turning on changes
|
|
99
|
+
|
|
100
|
+
Add two values to the same configuration block and restart the assistant:
|
|
101
|
+
|
|
102
|
+
- `GOOGLE_ADS_ENABLE_WRITES=true`
|
|
103
|
+
- `GOOGLE_ADS_WRITE_CUSTOMER_IDS=1234567890,2345678901` (only these accounts can ever be changed, whatever else can be read)
|
|
104
|
+
|
|
105
|
+
Every change is then drafted, shown as a preview that names the account and the spend limits that apply, and sent only by a separate confirm step. For an agency, give each client its own website domain, banned words and spend limits in `advertiser.yaml`; see [advertiser.example.yaml](advertiser.example.yaml).
|
|
106
|
+
|
|
107
|
+
## Every tool, in plain words
|
|
108
|
+
|
|
109
|
+
Accounts
|
|
110
|
+
- `health_check`: is the sign-in working, and how many accounts can it reach.
|
|
111
|
+
- `find_accounts`: search the accounts under your manager account by name.
|
|
112
|
+
- `use_account`, `current_account`: pick the account reports use, and show the pick. Reports only; a change always names its account.
|
|
113
|
+
- `list_accounts`: the accounts named in your configuration.
|
|
114
|
+
- `get_account_info`: one account's name, currency, time zone and status.
|
|
115
|
+
|
|
116
|
+
Reports
|
|
117
|
+
- `get_campaign_performance`, `get_ad_performance`, `get_keyword_performance`, `get_search_terms`, `get_geo_performance`: the standard reports, last 30 days unless you give dates.
|
|
118
|
+
- `run_gaql`: any custom report, with ready-made recipes in its description.
|
|
119
|
+
- `describe_fields`: what a custom report can ask for, so nobody needs Google's field names.
|
|
120
|
+
- `get_negative_keywords`, `list_extensions`, `get_policy_issues`, `get_conversion_actions`, `list_recommendations`, `get_entities`, `search_geo_targets`: look up what is in the account.
|
|
121
|
+
- `discover_keywords`, `get_keyword_forecasts`: Keyword Planner ideas and forecasts.
|
|
122
|
+
|
|
123
|
+
Changes to what exists (all drafted first)
|
|
124
|
+
- `update_campaign`, `update_ad_group`: budget, name, status, target CPA or ROAS, ad-group bid.
|
|
125
|
+
- `pause_entity`, `enable_entity`, `remove_entity`: pause, resume or permanently remove.
|
|
126
|
+
- `draft_keywords`, `remove_keywords`, `update_keyword_bid`: keywords and their bids.
|
|
127
|
+
- `add_negative_keywords`, `remove_negative_keywords`, `create_shared_negative_set`, `add_to_shared_set`, `attach_shared_set`: negative keywords and shared lists.
|
|
128
|
+
- `exclude_geo_target`, `remove_geo_target`, `set_campaign_schedule`: locations and ad schedule.
|
|
129
|
+
- `add_audience_targeting`, `create_custom_audience`, `set_listing_group_filter`: audiences and product filters.
|
|
130
|
+
|
|
131
|
+
Creating new things (always created paused)
|
|
132
|
+
- `draft_campaign`, `create_ad_group`, `draft_responsive_search_ad`: Search campaigns, ad groups and ads.
|
|
133
|
+
- `create_pmax_campaign`, `create_asset_group`, `update_asset_group`, `add_asset_group_assets`, `remove_asset_group_asset`: Performance Max.
|
|
134
|
+
- `create_demand_gen_campaign`, `draft_demand_gen_ad`: Demand Gen.
|
|
135
|
+
- `create_portfolio_bidding_strategy`: shared bid strategies.
|
|
136
|
+
- `draft_sitelinks`, `create_callouts`, `create_structured_snippets`, `remove_extension`, `upload_image_asset`, `upload_text_asset`: assets and extensions.
|
|
137
|
+
- `create_conversion_action`, `set_conversion_action_primary_status`, `apply_recommendation`, `dismiss_recommendation`: conversions and Google's suggestions, each behind its own extra switch.
|
|
138
|
+
|
|
139
|
+
Applying and undoing
|
|
140
|
+
- `confirm_and_apply`: send a drafted change. The only tool that changes anything.
|
|
141
|
+
- `undo_change`: draft the reverse of a change already made.
|
|
142
|
+
|
|
143
|
+
Inputs, limits, and what has and has not been tested live are in the [tool reference](docs/tool-reference.md). Creation tools deliberately support a narrow set of campaign shapes. If you need every knob in the Google Ads UI, this is not that.
|
|
144
|
+
|
|
145
|
+
## How a change actually happens
|
|
146
|
+
|
|
147
|
+
```text
|
|
148
|
+
assistant calls update_campaign(...)
|
|
149
|
+
-> server checks: writes enabled? account on the write allowlist? feature opt-in set?
|
|
150
|
+
-> server reads current state, checks budget / bid ceilings and bidding rules
|
|
151
|
+
-> returns a preview plus a draft id (expires in 60 min, dies on restart)
|
|
152
|
+
|
|
153
|
+
assistant calls confirm_and_apply(draft_id)
|
|
154
|
+
-> server re-reads account state, re-runs the same checks
|
|
155
|
+
-> sends exactly one mutate to Google
|
|
156
|
+
-> appends the outcome to ~/.mcp-google-ads-safe/audit.jsonl
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
If Google's answer is ambiguous (a timeout after the request left the building), the server records the outcome as unknown and refuses to retry on its own. You read the account and decide.
|
|
160
|
+
|
|
161
|
+
Changed your mind? `undo_change(draft_id)` reads the audit log, finds what the original change replaced, and drafts the reverse. It is a normal draft: same caps, same allowlists, same confirm step, and a fresh look at the account before anything is sent. Budgets, names, statuses, targets, bids, keyword and negative additions or removals, and schedules can be reversed. A creation that has since been enabled gets paused. Removals and asset uploads are permanent at Google, and undo says so instead of pretending.
|
|
162
|
+
|
|
163
|
+
Things worth being honest about:
|
|
164
|
+
|
|
165
|
+
- `confirm_and_apply` is a second call, not a human approval step. Any connected client holding the draft id can confirm it. If you want a person in the loop, do the confirm yourself or run the server in read-only mode and use it for reporting.
|
|
166
|
+
- Ceilings are per-operation limits, not an account spend guarantee. A cap on daily budget does not stop ten campaigns each at the cap.
|
|
167
|
+
- State checks are point-in-time. A change made in the Google Ads UI between preview and confirm can still slip through if it does not alter the fields the server compares.
|
|
168
|
+
- Drafts live in the server process's memory. Restart the server and they are gone.
|
|
169
|
+
- If you enable writes without setting a write allowlist, the default account from `GOOGLE_ADS_CUSTOMER_ID` becomes writable. Set the allowlist explicitly.
|
|
170
|
+
|
|
171
|
+
Details and every environment variable: [configuration](docs/configuration.md).
|
|
172
|
+
|
|
173
|
+
## Test coverage and live evidence
|
|
174
|
+
|
|
175
|
+
Every one of the 4,001 tests runs offline against a fake Google Ads API. CI runs them on Ubuntu and macOS across Python 3.12, 3.13, and 3.14 on every push. That proves the request shapes, the safety logic, and the refusal paths. It does not prove Google accepts a given operation on your account.
|
|
176
|
+
|
|
177
|
+
Live evidence is uneven and documented per tool. All reporting and lookup tools have been run against a real account. A subset of writes (budget, name, target CPA / ROAS, ad-group CPC, ad-group pause / enable, exact-match keywords, Manual CPC campaign and ad-group creation) has been applied to a real account and read back. Most of the Performance Max, Demand Gen, asset, conversion, and recommendation writes have offline tests only. The [evidence matrix](docs/offline-capability-matrix.md) says which is which. Read it before enabling writes for anything you would not want to fix by hand.
|
|
178
|
+
|
|
179
|
+
## Status
|
|
180
|
+
|
|
181
|
+
Version 2.0.0. Installs from GitHub with one command; a PyPI package is prepared but not published yet. CI runs lint, the full test suite on the newest and the oldest supported MCP library, a known-vulnerability audit of dependencies, and a high-severity Bandit scan, on Ubuntu and macOS across Python 3.12, 3.13, and 3.14. Windows has not been tested.
|
|
182
|
+
|
|
183
|
+
Upgrading from 1.x: report answers changed shape (readable rows plus `account` and `provenance` blocks; `run_gaql(raw=True)` returns the old rows), and `health_check` returns different keys. See the [changelog](CHANGELOG.md).
|
|
184
|
+
|
|
185
|
+
## Docs
|
|
186
|
+
|
|
187
|
+
- [Setup](docs/setup.md), [configuration](docs/configuration.md), [troubleshooting](docs/troubleshooting.md)
|
|
188
|
+
- [Tool reference](docs/tool-reference.md) and [evidence matrix](docs/offline-capability-matrix.md)
|
|
189
|
+
- [Contributing](CONTRIBUTING.md), [security policy](SECURITY.md), [changelog](CHANGELOG.md), [license](LICENSE)
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
# Google Ads MCP Safe
|
|
2
|
+
|
|
3
|
+
A Google Ads MCP server that lets an AI assistant change your account, with the brakes built into the server instead of the prompt.
|
|
4
|
+
|
|
5
|
+
MCP (Model Context Protocol) is the standard that lets assistants like Claude, Codex, or Cursor call tools. Most Google Ads MCP servers are either read-only (Google's own is, on purpose) or hand the assistant raw write access and hope for the best. This one sits in the middle: 64 tools that cover research, reporting, and account changes across Search, Performance Max, and Demand Gen, where every change has to pass a set of checks the assistant cannot talk its way around.
|
|
6
|
+
|
|
7
|
+
Independent, third-party project. Not affiliated with, endorsed by, or maintained by Google. Uses Google Ads API v25. MIT licensed.
|
|
8
|
+
|
|
9
|
+
## Why another Google Ads MCP?
|
|
10
|
+
|
|
11
|
+
I manage paid media day to day. I wanted an assistant that could pull search terms, draft negatives, and adjust a target CPA on a Monday morning without me worrying that a misread instruction would triple a budget or un-pause a campaign I had killed for a reason. The write-capable servers I found had one or two safeguards each. None had the full set, and the ones that came closest had a single user.
|
|
12
|
+
|
|
13
|
+
So the design goal here is simple: the assistant proposes, the server decides whether that proposal is allowed, and nothing reaches Google until a second explicit call says go.
|
|
14
|
+
|
|
15
|
+
### How it compares
|
|
16
|
+
|
|
17
|
+
| | Google official server | Typical community write server | Google Ads MCP Safe |
|
|
18
|
+
| --- | --- | --- | --- |
|
|
19
|
+
| Reads (GAQL, reports, account discovery) | Yes | Yes | Yes, readable, row-limited, each naming its account and dates |
|
|
20
|
+
| Agency use (many client accounts under one manager) | Varies | Varies | Find by name, read any, change only listed ones, per-client rules and spend limits |
|
|
21
|
+
| Writes | No, by design | Yes | Yes, off by default |
|
|
22
|
+
| Per-account write allowlist | n/a | Rare | Yes. Reads can optionally cover a whole manager account; changes never do |
|
|
23
|
+
| Preview then separate confirm call | n/a | Some | Yes, every write |
|
|
24
|
+
| Daily budget, CPC, and target CPA ceilings | n/a | Some | Yes, three separate caps |
|
|
25
|
+
| Refuses to clear a Performance Max target (budget still caps spend; this protects cost per result) | n/a | Not found | Yes |
|
|
26
|
+
| Extra opt-in for shared or blast-radius resources | n/a | Not found | Yes, seven separate switches (shared budgets, portfolios, conversion goals, shared audiences, recommendations, shared negative lists, permanent removal) |
|
|
27
|
+
| New campaigns, ad groups, ads created PAUSED | n/a | Some | Yes, always |
|
|
28
|
+
| Local audit log | n/a | Some log applied writes | Logs drafts, refusals, applies, and unknown outcomes |
|
|
29
|
+
| Fresh state re-check at confirm time | n/a | Not found | Yes |
|
|
30
|
+
| Undo for applied changes | n/a | Not found | Yes, drafts the reverse from the audit log |
|
|
31
|
+
| Automated tests | Unknown | Usually few or none | 4,001 |
|
|
32
|
+
|
|
33
|
+
"Typical community write server" summarizes the open-source write-capable servers I could find on GitHub in September 2026. The best of them ship two or three of these gates. To my knowledge none combine all of them in a maintained project, but I have not audited every repo, and this table is a snapshot, not a scoreboard. The [Google official server](https://developers.google.com/google-ads/api/docs/developer-toolkit/mcp-server) is the right choice if you only need reads and want Google-maintained code.
|
|
34
|
+
|
|
35
|
+
## What you can ask
|
|
36
|
+
|
|
37
|
+
Once connected, talk to your assistant in plain words. It picks the tools.
|
|
38
|
+
|
|
39
|
+
- "Find the Smith Dental account and use it."
|
|
40
|
+
- "How did each campaign do in the last 30 days? Show spend, conversions and cost per conversion."
|
|
41
|
+
- "Which search terms spent money with no conversions last month?"
|
|
42
|
+
- "What share of search impressions are we losing to budget, by campaign?"
|
|
43
|
+
- "Do the same check for the next client on my list."
|
|
44
|
+
- "Draft a negative keyword list from those search terms." (a change: previewed first, applied only on a second explicit step, and only if you turned changes on)
|
|
45
|
+
|
|
46
|
+
Every report says which account it came from, its currency and time zone, the exact dates it covers, and whether it was cut short. Money is shown in whole currency units, statuses as words. The standard performance reports return 100 rows unless you ask for more (up to 1,000). Custom queries and account lookups return up to one page (10,000 rows) and say when more exist, so add a limit to those yourself.
|
|
47
|
+
|
|
48
|
+
## Quick start
|
|
49
|
+
|
|
50
|
+
You need Python 3.12 or newer, [uv](https://docs.astral.sh/uv/) (a small tool that runs Python programs without a manual install), a Google Cloud project with Google Ads API access (the [setup guide](docs/setup.md) explains how to get one), and access to the account or manager account you want to use.
|
|
51
|
+
|
|
52
|
+
1. In your terminal (on a Mac, the Terminal app), run the guided setup. It asks three plain questions, opens Google's sign-in page, and saves a private sign-in file:
|
|
53
|
+
|
|
54
|
+
```sh
|
|
55
|
+
uvx --from git+https://github.com/wvuhskr/mcp-google-ads-safe mcp-google-ads-safe setup
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
2. Paste the configuration it prints into your assistant (Claude Desktop or Claude Code; other MCP clients take the same values).
|
|
59
|
+
3. Quit and reopen the assistant.
|
|
60
|
+
4. Ask it: "run health_check, then find_accounts".
|
|
61
|
+
5. Ask it: "use the account named ..." and start asking questions.
|
|
62
|
+
|
|
63
|
+
That setup is read-only and can report on every enabled account under your manager account. Nothing can be changed until you turn changes on. The package is not on PyPI yet, so the command above installs from GitHub. A service account, or a manual setup with explicit account lists, is in the [setup guide](docs/setup.md). To sign in again later: the same command with `reauth` in place of `setup`.
|
|
64
|
+
|
|
65
|
+
### Turning on changes
|
|
66
|
+
|
|
67
|
+
Add two values to the same configuration block and restart the assistant:
|
|
68
|
+
|
|
69
|
+
- `GOOGLE_ADS_ENABLE_WRITES=true`
|
|
70
|
+
- `GOOGLE_ADS_WRITE_CUSTOMER_IDS=1234567890,2345678901` (only these accounts can ever be changed, whatever else can be read)
|
|
71
|
+
|
|
72
|
+
Every change is then drafted, shown as a preview that names the account and the spend limits that apply, and sent only by a separate confirm step. For an agency, give each client its own website domain, banned words and spend limits in `advertiser.yaml`; see [advertiser.example.yaml](advertiser.example.yaml).
|
|
73
|
+
|
|
74
|
+
## Every tool, in plain words
|
|
75
|
+
|
|
76
|
+
Accounts
|
|
77
|
+
- `health_check`: is the sign-in working, and how many accounts can it reach.
|
|
78
|
+
- `find_accounts`: search the accounts under your manager account by name.
|
|
79
|
+
- `use_account`, `current_account`: pick the account reports use, and show the pick. Reports only; a change always names its account.
|
|
80
|
+
- `list_accounts`: the accounts named in your configuration.
|
|
81
|
+
- `get_account_info`: one account's name, currency, time zone and status.
|
|
82
|
+
|
|
83
|
+
Reports
|
|
84
|
+
- `get_campaign_performance`, `get_ad_performance`, `get_keyword_performance`, `get_search_terms`, `get_geo_performance`: the standard reports, last 30 days unless you give dates.
|
|
85
|
+
- `run_gaql`: any custom report, with ready-made recipes in its description.
|
|
86
|
+
- `describe_fields`: what a custom report can ask for, so nobody needs Google's field names.
|
|
87
|
+
- `get_negative_keywords`, `list_extensions`, `get_policy_issues`, `get_conversion_actions`, `list_recommendations`, `get_entities`, `search_geo_targets`: look up what is in the account.
|
|
88
|
+
- `discover_keywords`, `get_keyword_forecasts`: Keyword Planner ideas and forecasts.
|
|
89
|
+
|
|
90
|
+
Changes to what exists (all drafted first)
|
|
91
|
+
- `update_campaign`, `update_ad_group`: budget, name, status, target CPA or ROAS, ad-group bid.
|
|
92
|
+
- `pause_entity`, `enable_entity`, `remove_entity`: pause, resume or permanently remove.
|
|
93
|
+
- `draft_keywords`, `remove_keywords`, `update_keyword_bid`: keywords and their bids.
|
|
94
|
+
- `add_negative_keywords`, `remove_negative_keywords`, `create_shared_negative_set`, `add_to_shared_set`, `attach_shared_set`: negative keywords and shared lists.
|
|
95
|
+
- `exclude_geo_target`, `remove_geo_target`, `set_campaign_schedule`: locations and ad schedule.
|
|
96
|
+
- `add_audience_targeting`, `create_custom_audience`, `set_listing_group_filter`: audiences and product filters.
|
|
97
|
+
|
|
98
|
+
Creating new things (always created paused)
|
|
99
|
+
- `draft_campaign`, `create_ad_group`, `draft_responsive_search_ad`: Search campaigns, ad groups and ads.
|
|
100
|
+
- `create_pmax_campaign`, `create_asset_group`, `update_asset_group`, `add_asset_group_assets`, `remove_asset_group_asset`: Performance Max.
|
|
101
|
+
- `create_demand_gen_campaign`, `draft_demand_gen_ad`: Demand Gen.
|
|
102
|
+
- `create_portfolio_bidding_strategy`: shared bid strategies.
|
|
103
|
+
- `draft_sitelinks`, `create_callouts`, `create_structured_snippets`, `remove_extension`, `upload_image_asset`, `upload_text_asset`: assets and extensions.
|
|
104
|
+
- `create_conversion_action`, `set_conversion_action_primary_status`, `apply_recommendation`, `dismiss_recommendation`: conversions and Google's suggestions, each behind its own extra switch.
|
|
105
|
+
|
|
106
|
+
Applying and undoing
|
|
107
|
+
- `confirm_and_apply`: send a drafted change. The only tool that changes anything.
|
|
108
|
+
- `undo_change`: draft the reverse of a change already made.
|
|
109
|
+
|
|
110
|
+
Inputs, limits, and what has and has not been tested live are in the [tool reference](docs/tool-reference.md). Creation tools deliberately support a narrow set of campaign shapes. If you need every knob in the Google Ads UI, this is not that.
|
|
111
|
+
|
|
112
|
+
## How a change actually happens
|
|
113
|
+
|
|
114
|
+
```text
|
|
115
|
+
assistant calls update_campaign(...)
|
|
116
|
+
-> server checks: writes enabled? account on the write allowlist? feature opt-in set?
|
|
117
|
+
-> server reads current state, checks budget / bid ceilings and bidding rules
|
|
118
|
+
-> returns a preview plus a draft id (expires in 60 min, dies on restart)
|
|
119
|
+
|
|
120
|
+
assistant calls confirm_and_apply(draft_id)
|
|
121
|
+
-> server re-reads account state, re-runs the same checks
|
|
122
|
+
-> sends exactly one mutate to Google
|
|
123
|
+
-> appends the outcome to ~/.mcp-google-ads-safe/audit.jsonl
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
If Google's answer is ambiguous (a timeout after the request left the building), the server records the outcome as unknown and refuses to retry on its own. You read the account and decide.
|
|
127
|
+
|
|
128
|
+
Changed your mind? `undo_change(draft_id)` reads the audit log, finds what the original change replaced, and drafts the reverse. It is a normal draft: same caps, same allowlists, same confirm step, and a fresh look at the account before anything is sent. Budgets, names, statuses, targets, bids, keyword and negative additions or removals, and schedules can be reversed. A creation that has since been enabled gets paused. Removals and asset uploads are permanent at Google, and undo says so instead of pretending.
|
|
129
|
+
|
|
130
|
+
Things worth being honest about:
|
|
131
|
+
|
|
132
|
+
- `confirm_and_apply` is a second call, not a human approval step. Any connected client holding the draft id can confirm it. If you want a person in the loop, do the confirm yourself or run the server in read-only mode and use it for reporting.
|
|
133
|
+
- Ceilings are per-operation limits, not an account spend guarantee. A cap on daily budget does not stop ten campaigns each at the cap.
|
|
134
|
+
- State checks are point-in-time. A change made in the Google Ads UI between preview and confirm can still slip through if it does not alter the fields the server compares.
|
|
135
|
+
- Drafts live in the server process's memory. Restart the server and they are gone.
|
|
136
|
+
- If you enable writes without setting a write allowlist, the default account from `GOOGLE_ADS_CUSTOMER_ID` becomes writable. Set the allowlist explicitly.
|
|
137
|
+
|
|
138
|
+
Details and every environment variable: [configuration](docs/configuration.md).
|
|
139
|
+
|
|
140
|
+
## Test coverage and live evidence
|
|
141
|
+
|
|
142
|
+
Every one of the 4,001 tests runs offline against a fake Google Ads API. CI runs them on Ubuntu and macOS across Python 3.12, 3.13, and 3.14 on every push. That proves the request shapes, the safety logic, and the refusal paths. It does not prove Google accepts a given operation on your account.
|
|
143
|
+
|
|
144
|
+
Live evidence is uneven and documented per tool. All reporting and lookup tools have been run against a real account. A subset of writes (budget, name, target CPA / ROAS, ad-group CPC, ad-group pause / enable, exact-match keywords, Manual CPC campaign and ad-group creation) has been applied to a real account and read back. Most of the Performance Max, Demand Gen, asset, conversion, and recommendation writes have offline tests only. The [evidence matrix](docs/offline-capability-matrix.md) says which is which. Read it before enabling writes for anything you would not want to fix by hand.
|
|
145
|
+
|
|
146
|
+
## Status
|
|
147
|
+
|
|
148
|
+
Version 2.0.0. Installs from GitHub with one command; a PyPI package is prepared but not published yet. CI runs lint, the full test suite on the newest and the oldest supported MCP library, a known-vulnerability audit of dependencies, and a high-severity Bandit scan, on Ubuntu and macOS across Python 3.12, 3.13, and 3.14. Windows has not been tested.
|
|
149
|
+
|
|
150
|
+
Upgrading from 1.x: report answers changed shape (readable rows plus `account` and `provenance` blocks; `run_gaql(raw=True)` returns the old rows), and `health_check` returns different keys. See the [changelog](CHANGELOG.md).
|
|
151
|
+
|
|
152
|
+
## Docs
|
|
153
|
+
|
|
154
|
+
- [Setup](docs/setup.md), [configuration](docs/configuration.md), [troubleshooting](docs/troubleshooting.md)
|
|
155
|
+
- [Tool reference](docs/tool-reference.md) and [evidence matrix](docs/offline-capability-matrix.md)
|
|
156
|
+
- [Contributing](CONTRIBUTING.md), [security policy](SECURITY.md), [changelog](CHANGELOG.md), [license](LICENSE)
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# Security policy
|
|
2
|
+
|
|
3
|
+
## Supported versions
|
|
4
|
+
|
|
5
|
+
Security fixes go into the latest release on the `main` branch. Older versions are not patched; upgrade to the latest release to pick up a fix.
|
|
6
|
+
|
|
7
|
+
## Reporting a vulnerability
|
|
8
|
+
|
|
9
|
+
Use GitHub's private vulnerability reporting for this repository: open the **Security** tab and choose **Report a vulnerability**. That opens a private advisory only the maintainer can see. Do not open a public issue, pull request, or discussion for a suspected vulnerability.
|
|
10
|
+
|
|
11
|
+
A useful report includes:
|
|
12
|
+
|
|
13
|
+
- The version, operating system, Python version, and how you installed it.
|
|
14
|
+
- What the problem is and what an attacker could do with it.
|
|
15
|
+
- Minimal steps to reproduce, using synthetic data or an account you are authorized to test.
|
|
16
|
+
- Sanitized logs or screenshots with credentials and customer identifiers removed.
|
|
17
|
+
|
|
18
|
+
Never include OAuth client secrets, refresh or access tokens, developer tokens, service-account keys, complete credential files, real customer IDs, or advertising performance data. Describe sensitive evidence first; if it is needed, a safe way to share it can be agreed inside the advisory.
|
|
19
|
+
|
|
20
|
+
You should get an acknowledgement within a few days. This is a one-person project with no bug bounty and no guaranteed fix timeline, but reports are read and taken seriously. Please allow a fix to ship before publishing details that would let someone exploit the problem.
|
|
21
|
+
|
|
22
|
+
## Testing boundaries
|
|
23
|
+
|
|
24
|
+
Test only systems and accounts you own or have explicit permission to assess. Prefer synthetic data and the offline test suite. Do not change live campaigns, budgets, bids, or billing without the account owner's authorization. This policy does not authorize testing Google's systems or any other third party.
|
|
25
|
+
|
|
26
|
+
## Keeping your own installation safe
|
|
27
|
+
|
|
28
|
+
- Keep the credential file outside the project folder, readable only by you. The server refuses a credential file that contains keys other than the documented sign-in keys.
|
|
29
|
+
- Never commit credentials or paste them into issues, chats, or diagnostic output. If a secret leaks, revoke or rotate it through Google's own controls.
|
|
30
|
+
- Leave writes off unless you intend to change an account. The rails are a second line of defense, not a substitute for account permissions and reviewing previews.
|
|
31
|
+
- The local audit log can contain campaign names, keyword text, and IDs. Protect it like any other operational log.
|
|
32
|
+
|
|
33
|
+
## Trust boundaries
|
|
34
|
+
|
|
35
|
+
Everything the server returns is visible to the assistant client you connect. The draft-then-confirm flow is not a human approval step: any connected caller holding a draft id can confirm it. If you need a person in the loop, run the confirm yourself or keep the server read-only.
|