google-ads-mcp-server 0.2.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.
- google_ads_mcp_server-0.2.0/LICENSE +22 -0
- google_ads_mcp_server-0.2.0/PKG-INFO +532 -0
- google_ads_mcp_server-0.2.0/README.md +485 -0
- google_ads_mcp_server-0.2.0/agency/__init__.py +5 -0
- google_ads_mcp_server-0.2.0/agency/analysis_profiles.py +239 -0
- google_ads_mcp_server-0.2.0/agency/api.py +236 -0
- google_ads_mcp_server-0.2.0/agency/audit_retention.py +341 -0
- google_ads_mcp_server-0.2.0/agency/builtin_profiles/agency-weekly.md +21 -0
- google_ads_mcp_server-0.2.0/agency/builtin_profiles/agency-weekly.toml +19 -0
- google_ads_mcp_server-0.2.0/agency/builtin_profiles/ecommerce-audit.md +23 -0
- google_ads_mcp_server-0.2.0/agency/builtin_profiles/ecommerce-audit.toml +20 -0
- google_ads_mcp_server-0.2.0/agency/builtin_profiles/leads-audit.md +24 -0
- google_ads_mcp_server-0.2.0/agency/builtin_profiles/leads-audit.toml +20 -0
- google_ads_mcp_server-0.2.0/agency/channels_tools.py +1069 -0
- google_ads_mcp_server-0.2.0/agency/cli_alerts.py +203 -0
- google_ads_mcp_server-0.2.0/agency/config.py +195 -0
- google_ads_mcp_server-0.2.0/agency/customer_match_tools.py +561 -0
- google_ads_mcp_server-0.2.0/agency/dates.py +140 -0
- google_ads_mcp_server-0.2.0/agency/demand_gen_tools.py +545 -0
- google_ads_mcp_server-0.2.0/agency/demo.py +1136 -0
- google_ads_mcp_server-0.2.0/agency/diagnostics_tools.py +961 -0
- google_ads_mcp_server-0.2.0/agency/errors.py +246 -0
- google_ads_mcp_server-0.2.0/agency/experiment_tools.py +614 -0
- google_ads_mcp_server-0.2.0/agency/governance.py +426 -0
- google_ads_mcp_server-0.2.0/agency/governance_tools.py +349 -0
- google_ads_mcp_server-0.2.0/agency/keyword_planner_tools.py +431 -0
- google_ads_mcp_server-0.2.0/agency/locks.py +124 -0
- google_ads_mcp_server-0.2.0/agency/mcc_tools.py +656 -0
- google_ads_mcp_server-0.2.0/agency/measurement_tools.py +1050 -0
- google_ads_mcp_server-0.2.0/agency/modules.py +370 -0
- google_ads_mcp_server-0.2.0/agency/mutations.py +260 -0
- google_ads_mcp_server-0.2.0/agency/offline_conversions_tools.py +522 -0
- google_ads_mcp_server-0.2.0/agency/operations_tools.py +275 -0
- google_ads_mcp_server-0.2.0/agency/read_tools.py +1892 -0
- google_ads_mcp_server-0.2.0/agency/registry.py +41 -0
- google_ads_mcp_server-0.2.0/agency/remote_gateway.py +354 -0
- google_ads_mcp_server-0.2.0/agency/remote_onboarding.py +1349 -0
- google_ads_mcp_server-0.2.0/agency/remote_store.py +1278 -0
- google_ads_mcp_server-0.2.0/agency/reports.py +1101 -0
- google_ads_mcp_server-0.2.0/agency/resources.py +240 -0
- google_ads_mcp_server-0.2.0/agency/runtime.py +203 -0
- google_ads_mcp_server-0.2.0/agency/waste_intelligence.py +358 -0
- google_ads_mcp_server-0.2.0/agency/write_tools.py +2355 -0
- google_ads_mcp_server-0.2.0/google_ads_cli.py +59 -0
- google_ads_mcp_server-0.2.0/google_ads_connect.py +912 -0
- google_ads_mcp_server-0.2.0/google_ads_mcp_server.egg-info/PKG-INFO +532 -0
- google_ads_mcp_server-0.2.0/google_ads_mcp_server.egg-info/SOURCES.txt +86 -0
- google_ads_mcp_server-0.2.0/google_ads_mcp_server.egg-info/dependency_links.txt +1 -0
- google_ads_mcp_server-0.2.0/google_ads_mcp_server.egg-info/entry_points.txt +4 -0
- google_ads_mcp_server-0.2.0/google_ads_mcp_server.egg-info/requires.txt +23 -0
- google_ads_mcp_server-0.2.0/google_ads_mcp_server.egg-info/top_level.txt +4 -0
- google_ads_mcp_server-0.2.0/google_ads_server.py +1910 -0
- google_ads_mcp_server-0.2.0/pyproject.toml +79 -0
- google_ads_mcp_server-0.2.0/setup.cfg +4 -0
- google_ads_mcp_server-0.2.0/tests/test_ad_strength.py +344 -0
- google_ads_mcp_server-0.2.0/tests/test_auction_insights.py +261 -0
- google_ads_mcp_server-0.2.0/tests/test_audit_fixes.py +1134 -0
- google_ads_mcp_server-0.2.0/tests/test_audit_retention.py +317 -0
- google_ads_mcp_server-0.2.0/tests/test_connect.py +87 -0
- google_ads_mcp_server-0.2.0/tests/test_consent_coverage.py +266 -0
- google_ads_mcp_server-0.2.0/tests/test_core.py +137 -0
- google_ads_mcp_server-0.2.0/tests/test_customer_match.py +265 -0
- google_ads_mcp_server-0.2.0/tests/test_demand_gen_tools.py +225 -0
- google_ads_mcp_server-0.2.0/tests/test_demo_and_doctor.py +260 -0
- google_ads_mcp_server-0.2.0/tests/test_dry_run.py +125 -0
- google_ads_mcp_server-0.2.0/tests/test_enhanced_conversions.py +368 -0
- google_ads_mcp_server-0.2.0/tests/test_errors.py +317 -0
- google_ads_mcp_server-0.2.0/tests/test_experiment_tools.py +209 -0
- google_ads_mcp_server-0.2.0/tests/test_expiring_approvals.py +167 -0
- google_ads_mcp_server-0.2.0/tests/test_governance_diff.py +210 -0
- google_ads_mcp_server-0.2.0/tests/test_guardrails.py +136 -0
- google_ads_mcp_server-0.2.0/tests/test_hygiene.py +57 -0
- google_ads_mcp_server-0.2.0/tests/test_impression_share.py +309 -0
- google_ads_mcp_server-0.2.0/tests/test_keyword_planner.py +191 -0
- google_ads_mcp_server-0.2.0/tests/test_locks.py +147 -0
- google_ads_mcp_server-0.2.0/tests/test_mcc_bulk_apply.py +244 -0
- google_ads_mcp_server-0.2.0/tests/test_offline_conversions_tools.py +372 -0
- google_ads_mcp_server-0.2.0/tests/test_phase1_catalog_profiles.py +223 -0
- google_ads_mcp_server-0.2.0/tests/test_phase1_runtime_dates.py +202 -0
- google_ads_mcp_server-0.2.0/tests/test_phase2_measurement.py +273 -0
- google_ads_mcp_server-0.2.0/tests/test_phase3a_diagnostics.py +188 -0
- google_ads_mcp_server-0.2.0/tests/test_phase3b_channels.py +120 -0
- google_ads_mcp_server-0.2.0/tests/test_phase4_operations.py +330 -0
- google_ads_mcp_server-0.2.0/tests/test_protocol.py +129 -0
- google_ads_mcp_server-0.2.0/tests/test_remote_gateway.py +101 -0
- google_ads_mcp_server-0.2.0/tests/test_remote_self_serve.py +1765 -0
- google_ads_mcp_server-0.2.0/tests/test_reports_bugs.py +251 -0
- google_ads_mcp_server-0.2.0/tests/test_waste_intelligence.py +177 -0
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Ernesto Cohnen - ixigo
|
|
4
|
+
Copyright (c) 2026 Fidel
|
|
5
|
+
|
|
6
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
7
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
8
|
+
in the Software without restriction, including without limitation the rights
|
|
9
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
10
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
11
|
+
furnished to do so, subject to the following conditions:
|
|
12
|
+
|
|
13
|
+
The above copyright notice and this permission notice shall be included in all
|
|
14
|
+
copies or substantial portions of the Software.
|
|
15
|
+
|
|
16
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
17
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
18
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
19
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
20
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
21
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
22
|
+
SOFTWARE.
|
|
@@ -0,0 +1,532 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: google-ads-mcp-server
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Open-source Google Ads MCP server with audits, multi-currency reporting, and safety guardrails
|
|
5
|
+
Author: Fidel
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/fidelp27/mcp-googleads
|
|
8
|
+
Project-URL: Repository, https://github.com/fidelp27/mcp-googleads
|
|
9
|
+
Project-URL: Issues, https://github.com/fidelp27/mcp-googleads/issues
|
|
10
|
+
Project-URL: Documentation, https://github.com/fidelp27/mcp-googleads#readme
|
|
11
|
+
Project-URL: Changelog, https://github.com/fidelp27/mcp-googleads/blob/main/CHANGELOG.md
|
|
12
|
+
Keywords: mcp,google ads,automation,analytics,reporting
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
|
|
22
|
+
Classifier: Topic :: Office/Business :: Financial
|
|
23
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
24
|
+
Requires-Python: >=3.11
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
License-File: LICENSE
|
|
27
|
+
Requires-Dist: filelock>=3.12
|
|
28
|
+
Requires-Dist: google-auth>=2.25.2
|
|
29
|
+
Requires-Dist: google-auth-oauthlib>=1.2.1
|
|
30
|
+
Requires-Dist: mcp[cli]<2,>=1.12.0
|
|
31
|
+
Requires-Dist: pydantic>=2.0
|
|
32
|
+
Requires-Dist: python-dotenv>=1.0.0
|
|
33
|
+
Requires-Dist: requests>=2.31.0
|
|
34
|
+
Requires-Dist: tzdata>=2024.1; sys_platform == "win32"
|
|
35
|
+
Provides-Extra: remote
|
|
36
|
+
Requires-Dist: PyJWT[crypto]<3,>=2.10; extra == "remote"
|
|
37
|
+
Requires-Dist: cryptography>=42.0; extra == "remote"
|
|
38
|
+
Requires-Dist: httpx<1,>=0.27; extra == "remote"
|
|
39
|
+
Requires-Dist: starlette<1,>=0.27; extra == "remote"
|
|
40
|
+
Requires-Dist: uvicorn<1,>=0.31; extra == "remote"
|
|
41
|
+
Provides-Extra: dev
|
|
42
|
+
Requires-Dist: pytest>=8.0; extra == "dev"
|
|
43
|
+
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
|
|
44
|
+
Requires-Dist: setuptools>=61.0; extra == "dev"
|
|
45
|
+
Requires-Dist: wheel; extra == "dev"
|
|
46
|
+
Dynamic: license-file
|
|
47
|
+
|
|
48
|
+
# Google Ads MCP Server (`google-ads-mcp-server`)
|
|
49
|
+
|
|
50
|
+
> **Español:** Ver la [guía rápida y ejemplos por rol en español](docs/es/README.md) y la [guía de conexión](docs/connect.md).
|
|
51
|
+
|
|
52
|
+
An open-source, **read-only-by-default** **Model Context Protocol (MCP)** server for auditing, reporting, diagnosing, and safely managing Google Ads accounts from desktop and CLI AI apps (**Claude Desktop, Claude Code, Codex, Antigravity, Gemini CLI, Cherry Studio / Cline / Cursor / VS Code with DeepSeek, Kimi, OpenAI, Anthropic, or Gemini**).
|
|
53
|
+
|
|
54
|
+
Built to complement Google's official MCP server with **142 structured tools** (74 read/diagnostic/analytics tools + 68 opt-in guarded write/governance tools), **10 modular domains**, **5 one-word presets**, **editable Markdown + TOML analysis profiles**, **account-timezone & truncation-safe analytics**, **multi-currency & multi-MCC orchestration**, and **human-in-the-loop write guardrails**.
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## Table of Contents
|
|
59
|
+
|
|
60
|
+
1. [What This MCP Does (Overview)](#what-this-mcp-does-overview)
|
|
61
|
+
2. [Quickstart in 30 Seconds (`--demo`)](#quickstart-in-30-seconds---demo)
|
|
62
|
+
3. [Connect Real Accounts (`connect` + `doctor` + `register`)](#connect-real-accounts-connect--doctor--register)
|
|
63
|
+
4. [Modular Tool Catalog & Presets (`--preset` / `--modules`)](#modular-tool-catalog--presets---preset----modules)
|
|
64
|
+
5. [Complete Functionality & Tool Reference (All 142 Tools)](#complete-functionality--tool-reference-all-142-tools)
|
|
65
|
+
- [Core Module (25 tools — loaded by default)](#1-core-module-25-tools--loaded-by-default)
|
|
66
|
+
- [Diagnostics Module (5 tools)](#2-diagnostics-module-5-tools)
|
|
67
|
+
- [Measurement Module (8 tools)](#3-measurement-module-8-tools)
|
|
68
|
+
- [Search Module (16 tools)](#4-search-module-16-tools)
|
|
69
|
+
- [Performance Max Module (8 tools)](#5-performance-max-module-8-tools)
|
|
70
|
+
- [Shopping Module (6 tools)](#6-shopping-module-6-tools)
|
|
71
|
+
- [Display Module (5 tools)](#7-display-module-5-tools)
|
|
72
|
+
- [Demand Gen Module (5 tools)](#8-demand-gen-module-5-tools)
|
|
73
|
+
- [MCC & Agency Governance Read Module (11 tools)](#9-mcc--agency-governance-read-module-11-tools)
|
|
74
|
+
- [Operations Module (68 guarded write & governance tools — opt-in only)](#10-operations-module-68-guarded-write--governance-tools--opt-in-only)
|
|
75
|
+
6. [MCP Prompts & Resources](#mcp-prompts--resources)
|
|
76
|
+
7. [Customizable Analysis Profiles (Markdown + TOML)](#customizable-analysis-profiles-markdown--toml)
|
|
77
|
+
8. [CLI Commands & Scheduled Alerts](#cli-commands--scheduled-alerts)
|
|
78
|
+
9. [Data Accuracy, Truncation & Safety Architecture](#data-accuracy-truncation--safety-architecture)
|
|
79
|
+
10. [Client Compatibility & Self-Hosted HTTP](#client-compatibility--self-hosted-http)
|
|
80
|
+
11. [Development & Documentation](#development--documentation)
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## What This MCP Does (Overview)
|
|
85
|
+
|
|
86
|
+
- **Zero-credential `--demo` sandbox:** Test the full read/reporting/audit workflow in 30 seconds against two synthetic accounts (`1111111111` EUR ecommerce in `Europe/Madrid` + `2222222222` USD B2B Leads in `America/New_York`) before touching Google Cloud.
|
|
87
|
+
- **Guided desktop onboarding & preflight (`connect`, `register`, `doctor`, `serve`):** Browser OAuth flow, direct & multi-account/MCC scoping (`--all-mcc-clients`), preset persistence (`--preset`, `--modules`), and actionable diagnostics (`doctor` / `doctor --offline` / `doctor --json`) that separate credential errors, Cloud project access-level limits, permission issues, and zero-data test accounts.
|
|
88
|
+
- **Compact modular tool surface:** Default `core` exposes **25 focused tools** (strictly validated against a multi-AI JSON Schema linter with no untyped `dict[str, Any]` parameters) so tool calling stays accurate and low-token across Claude, OpenAI, Gemini, DeepSeek, and Kimi.
|
|
89
|
+
- **360° operational diagnostics:**
|
|
90
|
+
- **Delivery & policy:** Combines account status, `billing_setup`, `account_budget`, campaign serving reasons, impression share losses, and ad/asset/keyword disapprovals into `confirmed_causes`, `hypotheses`, and `insufficient_data`.
|
|
91
|
+
- **Budget pacing:** Month-to-date spend, 7-day vs. MTD run rate, end-of-month projection, remaining budget, and required daily spend in the account's time zone.
|
|
92
|
+
- **Channel depth:** Search (terms, n-gram clusters, Quality Score 3-component breakdown, RSA Ad Strength, Keyword Planner, Experiments, Auction Insights API + EN/ES UI CSV fallback), Performance Max (asset groups, v25 asset `primary_status`/approvals, signals, listing filters, per-campaign search themes with explicit sampling coverage, placements), Shopping (SKU/brand/category/product-group ROAS & wasted spend), Display & Demand Gen (placements, mobile-app waste, video view rate & quartile funnel `p25/p50/p75/p100`).
|
|
93
|
+
- **Conversion & offline measurement audits:** Maps conversion ownership (account vs. MCC), account/campaign/custom goals (`conversion_goal_campaign_config`), secondary actions promoted into custom goals, Smart Bidding alignment, double-counting risks, Enhanced Conversions prerequisites, honest primary-vs-all measurement scope (never false-positive Consent Mode claims), offline upload health without PII, and **Data Manager API** upgrade eligibility.
|
|
94
|
+
- **Trustworthy reporting & multi-currency/multi-MCC accuracy:** Account-timezone closed days (`complete_days_only=True`), `queried_at_utc`, `conversion_lag_warning`, interaction-date vs. `conversions_by_conversion_date` time series, separated per-currency agency totals, dynamic per-account `login-customer-id` routing, row caps (`GOOGLE_ADS_MAX_SEARCH_ROWS`) with `truncated` / `totals_are_partial`, and automatic downgrade of absence-based alerts to `insufficient_data` when backing queries are truncated.
|
|
95
|
+
- **Guarded write engine (opt-in only):** When `READ_ONLY_MODE=true` (the default, and always enforced in managed desktop profiles), all 68 write tools in `operations` are **omitted from `tools/list`**. When explicitly enabled (`READ_ONLY_MODE=false`), mutations enforce mandatory `dry_run=true` (`validateOnly=true`) previews with diffs, exact confirmation phrases, economic caps, optimistic locking (`state_verifier`), partial retry for multi-account batches (`mcc_bulk_apply`), PII-redacted append-only audit logs, and `revert_operation`.
|
|
96
|
+
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
## Quickstart in 30 Seconds (`--demo`)
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
pip install google-ads-mcp-server
|
|
103
|
+
# or from a local checkout:
|
|
104
|
+
# pip install -e ".[dev]"
|
|
105
|
+
|
|
106
|
+
# Register zero-credential demo mode in your desktop AI client:
|
|
107
|
+
google-ads-mcp-server register --client claude-desktop --demo
|
|
108
|
+
# Optional: include domain modules via --preset (e.g. leads, ecommerce, agency, full):
|
|
109
|
+
google-ads-mcp-server register --client generic --demo --preset ecommerce
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Or run directly over `stdio`:
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
google-ads-mcp-server --transport stdio --demo --preset ecommerce
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Example prompts to try immediately in demo mode:
|
|
119
|
+
- *"List my accessible accounts and build a multi-currency agency dashboard."*
|
|
120
|
+
- *"Load the `leads-audit` analysis profile and audit account `2222222222`."*
|
|
121
|
+
- *"Diagnose delivery issues, budget pacing, and wasted search terms on account `1111111111`."*
|
|
122
|
+
- *"Run `get_pmax_diagnostics` and `get_shopping_performance` on account `1111111111`."*
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
## Connect Real Accounts (`connect` + `doctor` + `register`)
|
|
127
|
+
|
|
128
|
+
1. Enable **Google Ads API** in a Google Cloud project and download a **Desktop app** OAuth client JSON ([detailed setup guide](docs/connect.md)).
|
|
129
|
+
2. Authorize in your browser, select account(s) and optional preset/modules, and run `doctor`:
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
# Direct account with default compact catalog (`core`, 25 tools)
|
|
133
|
+
google-ads-mcp-server connect --client claude-desktop --customer 1234567890 --oauth-client /path/to/client_secret.json
|
|
134
|
+
|
|
135
|
+
# Direct account with ecommerce modules (PMax, Shopping, Measurement, Diagnostics)
|
|
136
|
+
google-ads-mcp-server connect --client codex --customer 1234567890 --preset ecommerce --oauth-client /path/to/client_secret.json
|
|
137
|
+
|
|
138
|
+
# MCC account scoping all enabled child accounts
|
|
139
|
+
google-ads-mcp-server connect --client antigravity --manager 9999999999 --all-mcc-clients --preset agency --oauth-client /path/to/client_secret.json
|
|
140
|
+
|
|
141
|
+
# Reuse the saved profile in another client
|
|
142
|
+
google-ads-mcp-server register --client gemini-cli --preset leads
|
|
143
|
+
|
|
144
|
+
# Verify credentials, API access, currency/timezone, and recent data
|
|
145
|
+
google-ads-mcp-server doctor
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Supported `--client` targets: `claude-desktop`, `claude-code`, `codex`, `antigravity`, `gemini-cli`, `generic` (outputs standard `{"mcpServers": ...}` JSON for Cursor, VS Code, Cherry Studio, Cline, Kimi CLI, etc.).
|
|
149
|
+
|
|
150
|
+
Managed profiles **always** launch with `READ_ONLY_MODE=true` and scope access strictly to the authorized customer IDs (plus manager ID if configured).
|
|
151
|
+
|
|
152
|
+
### Manual Claude Desktop config (fallback)
|
|
153
|
+
|
|
154
|
+
If you prefer to edit `claude_desktop_config.json` by hand instead of using `connect` / `register`, open it from Claude Desktop → *Settings → Developer → Edit Config* and paste a block like this under `mcpServers` (edit paths and IDs):
|
|
155
|
+
|
|
156
|
+
**Windows**
|
|
157
|
+
|
|
158
|
+
```json
|
|
159
|
+
{
|
|
160
|
+
"mcpServers": {
|
|
161
|
+
"google-ads": {
|
|
162
|
+
"command": "uvx",
|
|
163
|
+
"args": ["google-ads-mcp-server", "--transport", "stdio", "--preset", "core"],
|
|
164
|
+
"env": {
|
|
165
|
+
"GOOGLE_ADS_AUTH_TYPE": "oauth",
|
|
166
|
+
"GOOGLE_ADS_CLIENT_ID": "YOUR_OAUTH_CLIENT_ID",
|
|
167
|
+
"GOOGLE_ADS_CLIENT_SECRET": "YOUR_OAUTH_CLIENT_SECRET",
|
|
168
|
+
"GOOGLE_ADS_TOKEN_PATH": "C:\\Users\\YOU\\.google-ads\\token.json",
|
|
169
|
+
"GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN",
|
|
170
|
+
"GOOGLE_ADS_LOGIN_CUSTOMER_ID": "1234567890",
|
|
171
|
+
"ALLOWED_CUSTOMER_IDS": "1234567890,0987654321",
|
|
172
|
+
"READ_ONLY_MODE": "true",
|
|
173
|
+
"OPERATOR_NAME": "you"
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
**macOS / Linux**
|
|
181
|
+
|
|
182
|
+
```json
|
|
183
|
+
{
|
|
184
|
+
"mcpServers": {
|
|
185
|
+
"google-ads": {
|
|
186
|
+
"command": "uvx",
|
|
187
|
+
"args": ["google-ads-mcp-server", "--transport", "stdio", "--preset", "core"],
|
|
188
|
+
"env": {
|
|
189
|
+
"GOOGLE_ADS_AUTH_TYPE": "oauth",
|
|
190
|
+
"GOOGLE_ADS_CLIENT_ID": "YOUR_OAUTH_CLIENT_ID",
|
|
191
|
+
"GOOGLE_ADS_CLIENT_SECRET": "YOUR_OAUTH_CLIENT_SECRET",
|
|
192
|
+
"GOOGLE_ADS_TOKEN_PATH": "/Users/you/.google-ads/token.json",
|
|
193
|
+
"GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN",
|
|
194
|
+
"GOOGLE_ADS_LOGIN_CUSTOMER_ID": "1234567890",
|
|
195
|
+
"ALLOWED_CUSTOMER_IDS": "1234567890,0987654321",
|
|
196
|
+
"READ_ONLY_MODE": "true",
|
|
197
|
+
"OPERATOR_NAME": "you"
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
`uvx` auto-installs the package on first run (requires [`uv`](https://docs.astral.sh/uv/)). If you prefer pipx: replace `"command": "uvx"` with `"command": "google-ads-mcp-server"` and drop `google-ads-mcp-server` from `args`, after `pipx install google-ads-mcp-server`.
|
|
205
|
+
|
|
206
|
+
**Zero-credential demo** (no Google Cloud project needed):
|
|
207
|
+
|
|
208
|
+
```json
|
|
209
|
+
{
|
|
210
|
+
"mcpServers": {
|
|
211
|
+
"google-ads-demo": {
|
|
212
|
+
"command": "uvx",
|
|
213
|
+
"args": ["google-ads-mcp-server", "--transport", "stdio", "--demo", "--preset", "ecommerce"]
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
After editing, fully quit and reopen Claude Desktop so it picks up the new server.
|
|
220
|
+
|
|
221
|
+
---
|
|
222
|
+
|
|
223
|
+
## Modular Tool Catalog & Presets (`--preset` / `--modules`)
|
|
224
|
+
|
|
225
|
+
Instead of overwhelming LLMs with all 142 tools at once, only `core` (**25 tools**) loads by default. Activate domain modules with `--preset` or `--modules` (in `connect`, `register`, `serve`, CLI flags, or `GOOGLE_ADS_PRESET` / `GOOGLE_ADS_MODULES`):
|
|
226
|
+
|
|
227
|
+
| Preset | Active Modules | Active Tools (Read-Only) | Best For |
|
|
228
|
+
| --- | --- | :---: | --- |
|
|
229
|
+
| `core` *(default)* | `core` | 25 | Account overview, GAQL, trends, reports, waste, alerts, analysis profiles |
|
|
230
|
+
| `leads` | `core, diagnostics, measurement, search` | 54 | Search lead-gen audits, conversions, delivery, pacing, keywords, RSAs |
|
|
231
|
+
| `ecommerce` | `core, diagnostics, measurement, pmax, shopping` | 47 | PMax asset groups & placements, Shopping SKU/brand ROAS, pacing, tracking |
|
|
232
|
+
| `agency` | `core, diagnostics, measurement, search, pmax, mcc` | 71 | Multi-account MCC operations, multi-currency dashboards, weekly reviews |
|
|
233
|
+
| `full` | All read modules (+ `operations` **only** if `READ_ONLY_MODE=false`) | 74 *(142 when writes enabled)* | Full power-user read or read+write surface |
|
|
234
|
+
|
|
235
|
+
Fine-grained selection example:
|
|
236
|
+
|
|
237
|
+
```bash
|
|
238
|
+
google-ads-mcp-server --transport stdio --modules core,diagnostics,measurement,pmax
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
> **Hard safety invariant:** While `READ_ONLY_MODE=true` (default), all **68 tools** in `operations` are **completely excluded from `tools/list`** even when `--preset full` is passed.
|
|
242
|
+
|
|
243
|
+
---
|
|
244
|
+
|
|
245
|
+
## Complete Functionality & Tool Reference (All 142 Tools)
|
|
246
|
+
|
|
247
|
+
### 1. `core` Module (25 tools — loaded by default)
|
|
248
|
+
|
|
249
|
+
Account discovery, safe GAQL, core campaign/ad/creative read, time-series trends, reports, waste detection, alerts, and customizable analysis profiles.
|
|
250
|
+
|
|
251
|
+
| Tool | What It Does |
|
|
252
|
+
| --- | --- |
|
|
253
|
+
| `server_status` | Reports server readiness, auth mode, API version, guardrail posture (`read_only_mode`, scoped accounts), and active tool catalog/modules. |
|
|
254
|
+
| `list_accounts` | Lists accessible Google Ads customer IDs (or synthetic accounts in `--demo` mode). |
|
|
255
|
+
| `get_account_currency` | Retrieves account currency code and metadata. |
|
|
256
|
+
| `list_resources` | Queries `googleAdsFieldService` to list available Google Ads API resources for GAQL discovery. |
|
|
257
|
+
| `execute_gaql_query` | Runs a read-only GAQL query via the core server endpoint (formatted summary output). |
|
|
258
|
+
| `run_gaql` | Runs a read-only GAQL query via the agency engine with bounded row protection and structured JSON output. |
|
|
259
|
+
| `get_campaign_performance` | Campaign metrics (impressions, clicks, CTR, CPC, cost, conversions, value, CPA) over configurable windows. |
|
|
260
|
+
| `get_ad_performance` | Ad-level performance across campaigns and ad groups. |
|
|
261
|
+
| `get_ad_creatives` | Reads RSA headlines, descriptions, paths, final URLs, and approval/ad strength fields. |
|
|
262
|
+
| `get_image_assets` | Lists image assets with dimensions, URLs, and metadata. |
|
|
263
|
+
| `download_image_asset` | Downloads an image asset locally for visual inspection or review. |
|
|
264
|
+
| `get_asset_usage` | Shows which campaigns/ad groups reference image and creative assets. |
|
|
265
|
+
| `analyze_image_assets` | Analyzes image asset dimensions, aspect ratios, and performance. |
|
|
266
|
+
| `get_budget_utilization` | Compares daily spend against configured campaign budgets to spot budget-capped or underspending campaigns. |
|
|
267
|
+
| `get_bidding_strategies` | Lists portfolio and campaign bidding strategies, targets, and campaign counts. |
|
|
268
|
+
| `get_change_history` | Reads Google Ads `change_event` history (who changed what resource and when) for troubleshooting. |
|
|
269
|
+
| `get_performance_trends` | Account or campaign time series (`total`, `daily`, or `weekly`) in the account's time zone with `conversions` (interaction date) alongside `conversions_by_conversion_date`, `conversion_lag_warning`, and `totals_are_partial`. |
|
|
270
|
+
| `compare_periods` | Compares two explicit (`YYYY-MM-DD:YYYY-MM-DD`) or preset (`week`, `month`, `quarter`) periods in the account's time zone with absolute and percentage deltas. |
|
|
271
|
+
| `generate_client_report` | Generates an executive client report (`json`, `markdown`, or `html`) with typed `ReportBranding`, period-over-period deltas, top campaigns/keywords, wasted search terms, optional recommendations, and truncation metadata. |
|
|
272
|
+
| `generate_agency_dashboard` | Consolidates performance across multiple accounts **strictly separated by currency** (`managed_totals_by_currency`), surfacing alerts, pending approvals, and per-client truncation flags. |
|
|
273
|
+
| `detect_waste` | Flags non-converting search terms, low-CTR keywords, non-converting ad groups, and budget-limited campaigns in the account's time zone with `totals_are_partial`. |
|
|
274
|
+
| `check_alerts` | Evaluates spend, CTR, CPA, and waste thresholds from `config/alerts.json` (`defaults` + per-account overrides). |
|
|
275
|
+
| `generate_optimization_plan` | Produces a prioritized, **non-executing** list of suggested `dry_run=true` MCP actions backed by account evidence. |
|
|
276
|
+
| `list_analysis_profiles` | Lists built-in and user-defined Markdown + TOML analysis profiles (`leads-audit`, `ecommerce-audit`, `agency-weekly`, plus custom profiles). |
|
|
277
|
+
| `get_analysis_profile` | Returns a profile's full Markdown instructions, effective TOML parameters/thresholds, reproducibility header, and security notice. |
|
|
278
|
+
|
|
279
|
+
---
|
|
280
|
+
|
|
281
|
+
### 2. `diagnostics` Module (5 tools)
|
|
282
|
+
|
|
283
|
+
Included in `leads`, `ecommerce`, `agency`, and `full` presets.
|
|
284
|
+
|
|
285
|
+
| Tool | What It Does |
|
|
286
|
+
| --- | --- |
|
|
287
|
+
| `diagnose_delivery` | 360° root-cause diagnosis for zero/dropped impressions: inspects account status, `billing_setup`, `account_budget`, campaign `primary_status`/`primary_status_reasons`, budget/rank impression share losses, and ad/asset/keyword policy disapprovals — separating findings into `confirmed_causes`, `hypotheses`, and `insufficient_data` (downgrading absence-based billing conclusions when `billing_setup` is truncated). |
|
|
288
|
+
| `get_budget_pacing` | Computes complete-day MTD spend in the account's time zone, 7-day vs. MTD daily run rate, projected end-of-month spend, remaining budget, required daily spend, and status (`on_track`, `underspending`, `overspending`) against an explicit target, TOML profile target, or inferred active daily budgets. |
|
|
289
|
+
| `get_landing_page_performance` | Landing page URL metrics (`landing_page_view`) including mobile-friendly click rate (`mobile_friendly_clicks_percentage`) and `speed_score`. |
|
|
290
|
+
| `get_demographics_performance` | Performance breakdowns by `age`, `gender`, `income`, `parental_status`, or `all`. |
|
|
291
|
+
| `get_assets_and_calls_performance` | Extension/asset metrics and policy approvals (`campaign_asset`) plus aggregate call metrics (`call_view`, zero PII). |
|
|
292
|
+
|
|
293
|
+
---
|
|
294
|
+
|
|
295
|
+
### 3. `measurement` Module (8 tools)
|
|
296
|
+
|
|
297
|
+
Included in `leads`, `ecommerce`, `agency`, and `full` presets.
|
|
298
|
+
|
|
299
|
+
| Tool | What It Does |
|
|
300
|
+
| --- | --- |
|
|
301
|
+
| `audit_conversion_tracking` | Unified conversion audit crossing `customer.conversion_tracking_setting` (MCC vs. account ownership, Customer Data Terms, EC4L), `conversion_action`, `customer_conversion_goal`, `campaign_conversion_goal`, `custom_conversion_goal`, `conversion_goal_campaign_config` (v25), campaign bidding strategies, and per-action volume. Flags MCC centralization, secondary actions inside custom goals, multiple primaries in the same category, and Smart Bidding alignment (degrading absence-based alerts to `insufficient_data` on truncation/optional-query failure). |
|
|
302
|
+
| `get_offline_conversion_diagnostics` | Inspects `offline_conversion_upload_client_summary` and `offline_conversion_upload_conversion_action_summary` (sent, accepted, pending, failed, error codes — **zero PII**), distinguishes API ingestion from ad attribution, and flags legacy upload integrations eligible for **Data Manager API** upgrade. |
|
|
303
|
+
| `get_conversion_actions` | Lists conversion actions with category, origin, type, attribution model, counting type, default value, and `primary_for_goal`. |
|
|
304
|
+
| `get_conversion_performance` | Conversion volume, value, and cost per conversion segmented by conversion action. |
|
|
305
|
+
| `get_enhanced_conversions_status` | Checks customer-level Enhanced Conversions for Leads and Customer Data Terms acceptance status. |
|
|
306
|
+
| `check_consent_signal_coverage` | Reports primary-vs-all conversion scope ratios (`conversions / all_conversions`) honestly as a measurement-scope metric (explicitly noting that Google Ads API does not expose per-event Consent Mode signals). |
|
|
307
|
+
| `get_customer_match_list_stats` | Reads CRM-based `user_list` membership status, size for Search/Display, match rate range, and eligibility. |
|
|
308
|
+
| `get_offline_user_data_job_status` | Tracks async `offline_user_data_job` status and failure reasons for Customer Match uploads. |
|
|
309
|
+
|
|
310
|
+
---
|
|
311
|
+
|
|
312
|
+
### 4. `search` Module (16 tools)
|
|
313
|
+
|
|
314
|
+
Included in `leads`, `agency`, and `full` presets.
|
|
315
|
+
|
|
316
|
+
| Tool | What It Does |
|
|
317
|
+
| --- | --- |
|
|
318
|
+
| `get_search_terms_report` | Search queries (`search_term_view`) with status (`ADDED`/`EXCLUDED`/`NONE`), spend, clicks, conversions, and value. |
|
|
319
|
+
| `get_keyword_performance` | Keyword metrics (`keyword_view`) with match type, Quality Score, and all **3 Quality Score subcomponents** (`creative_quality_score`, `post_click_quality_score`, `search_predicted_ctr`). |
|
|
320
|
+
| `get_impression_share_losses` | Campaign Search Impression Share, exact-match IS, and IS lost to budget vs. rank. |
|
|
321
|
+
| `get_ad_strength_diagnostics` | Audits Responsive Search Ad strength (`POOR`/`AVERAGE`/`GOOD`/`EXCELLENT`), policy approvals, and pinning. |
|
|
322
|
+
| `get_auction_insights` | Queries API `auction_insight_*` metrics when permitted by the developer token / Cloud project. |
|
|
323
|
+
| `analyze_auction_insights_csv` | Parses Google Ads UI Auction Insights CSV exports (**English and Spanish**) into competitor rankings and high-pressure overlap alerts whenever the API restricts `auction_insight_*`. |
|
|
324
|
+
| `get_shared_sets` | Lists shared negative keyword lists and campaign attachments. |
|
|
325
|
+
| `analyze_search_terms_clusters` | Groups search terms into n-gram clusters with aggregate spend, clicks, CTR, conversions, and CPA. |
|
|
326
|
+
| `suggest_negatives_from_clusters` | Suggests candidate negative keywords from high-spend, zero-conversion search term clusters (read-only advisory). |
|
|
327
|
+
| `generate_keyword_ideas` | Uses Google Ads Keyword Planner to discover new keyword ideas with search volumes and competition. |
|
|
328
|
+
| `generate_keyword_historical_metrics` | Retrieves historical monthly search volume, competition, and top-of-page bid ranges for seed keywords. |
|
|
329
|
+
| `generate_keyword_forecast` | Forecasts clicks, impressions, cost, and conversions for a keyword plan. |
|
|
330
|
+
| `find_geo_target_constants` | Searches Google Ads `geo_target_constant` IDs by city, region, or country name. |
|
|
331
|
+
| `list_experiments` | Lists Search/Performance experiments and their status. |
|
|
332
|
+
| `get_experiment` | Retrieves configuration and arms (control vs. treatment) of an experiment. |
|
|
333
|
+
| `get_experiment_results` | Compares control vs. treatment arm metrics with lift/delta calculations. |
|
|
334
|
+
|
|
335
|
+
---
|
|
336
|
+
|
|
337
|
+
### 5. `pmax` Module (8 tools)
|
|
338
|
+
|
|
339
|
+
Included in `ecommerce`, `agency`, and `full` presets.
|
|
340
|
+
|
|
341
|
+
| Tool | What It Does |
|
|
342
|
+
| --- | --- |
|
|
343
|
+
| `get_pmax_diagnostics` | Full Performance Max audit: `asset_group` strength/metrics, `asset_group_asset` v25 `primary_status`/`primary_status_reasons`/approvals, `asset_group_signal` (audiences & search themes), `asset_group_listing_group_filter`, per-campaign `campaign_search_term_insight` (top 10 PMax campaigns), and `performance_max_placement_view` (mobile-app impression alerts). Explicitly reports `coverage_status` (`complete` / `empty` / `sampled` / `partial_error`), `truncated_queries`, `search_term_insights_coverage`, `placements_coverage`, and `sampling_warnings`. |
|
|
344
|
+
| `analyze_auction_insights_csv` | Parses Google Ads UI Auction Insights CSV exports (EN/ES). |
|
|
345
|
+
| `get_geo_performance` | Performance breakdown by geographic location. |
|
|
346
|
+
| `get_device_performance` | Performance breakdown by device (`MOBILE`, `DESKTOP`, `TABLET`, `CONNECTED_TV`). |
|
|
347
|
+
| `get_time_of_day_performance` | Performance breakdown by day of week and hour of day. |
|
|
348
|
+
| `get_audience_performance` | Performance breakdown across audience segments. |
|
|
349
|
+
| `list_recommendations` | Lists active Google Ads recommendations (read-only review). |
|
|
350
|
+
| `get_recommendation_detail` | Inspects impact estimates and parameters of a specific recommendation. |
|
|
351
|
+
|
|
352
|
+
---
|
|
353
|
+
|
|
354
|
+
### 6. `shopping` Module (6 tools)
|
|
355
|
+
|
|
356
|
+
Included in `ecommerce` and `full` presets.
|
|
357
|
+
|
|
358
|
+
| Tool | What It Does |
|
|
359
|
+
| --- | --- |
|
|
360
|
+
| `get_shopping_performance` | Shopping performance grouped by `product` (SKU), `brand`, `category` (`shopping_performance_view`), or `product_group` (`product_group_view`), returning blended ROAS, `top_winners`, `wasted_products` above `min_waste_spend`, wasted-spend share %, and `totals_are_partial`. |
|
|
361
|
+
| `analyze_auction_insights_csv` | Parses Shopping Auction Insights UI CSV exports (EN/ES). |
|
|
362
|
+
| `get_geo_performance` | Geographic performance breakdown. |
|
|
363
|
+
| `get_device_performance` | Device performance breakdown. |
|
|
364
|
+
| `list_recommendations` | Lists Shopping/account recommendations. |
|
|
365
|
+
| `get_recommendation_detail` | Inspects a recommendation in detail. |
|
|
366
|
+
|
|
367
|
+
---
|
|
368
|
+
|
|
369
|
+
### 7. `display` Module (5 tools)
|
|
370
|
+
|
|
371
|
+
Included in `full` preset (or via `--modules display`).
|
|
372
|
+
|
|
373
|
+
| Tool | What It Does |
|
|
374
|
+
| --- | --- |
|
|
375
|
+
| `get_placements_and_video_performance` | Audits `detail_placement_view` (surfacing zero-conversion and `MOBILE_APPLICATION` exclusion candidates) alongside campaign video view rate, average CPV, and quartile funnel (`p25/p50/p75/p100`). |
|
|
376
|
+
| `get_audience_performance` | Audience segment performance. |
|
|
377
|
+
| `get_geo_performance` | Geographic performance. |
|
|
378
|
+
| `get_device_performance` | Device performance. |
|
|
379
|
+
| `get_time_of_day_performance` | Day-of-week & hour-of-day performance. |
|
|
380
|
+
|
|
381
|
+
---
|
|
382
|
+
|
|
383
|
+
### 8. `demand-gen` Module (5 tools)
|
|
384
|
+
|
|
385
|
+
Included in `full` preset (or via `--modules demand-gen`).
|
|
386
|
+
|
|
387
|
+
| Tool | What It Does |
|
|
388
|
+
| --- | --- |
|
|
389
|
+
| `get_demand_gen_performance` | Demand Gen campaign & ad group performance summary. |
|
|
390
|
+
| `get_placements_and_video_performance` | Placement brand-safety audit + video view rate & quartile retention (`p25/p50/p75/p100`). |
|
|
391
|
+
| `get_audience_performance` | Audience segment performance. |
|
|
392
|
+
| `get_geo_performance` | Geographic performance. |
|
|
393
|
+
| `get_device_performance` | Device performance. |
|
|
394
|
+
|
|
395
|
+
---
|
|
396
|
+
|
|
397
|
+
### 9. `mcc` Module (11 tools)
|
|
398
|
+
|
|
399
|
+
Included in `agency` and `full` presets.
|
|
400
|
+
|
|
401
|
+
| Tool | What It Does |
|
|
402
|
+
| --- | --- |
|
|
403
|
+
| `list_client_accounts` | Discovers active non-manager child accounts under a Manager Account (MCC) and automatically registers dynamic per-account `login-customer-id` routing for the session. |
|
|
404
|
+
| `get_client_context` | Returns the active client context and configured client metadata. |
|
|
405
|
+
| `switch_context` | Switches the active client context for multi-account agency sessions. |
|
|
406
|
+
| `run_across_clients` | Runs a read-only GAQL query in parallel across multiple client accounts (respecting per-account MCC routing and `ALLOWED_CUSTOMER_IDS`). |
|
|
407
|
+
| `generate_agency_dashboard` | Multi-account consolidated dashboard separated by currency. |
|
|
408
|
+
| `get_audit_log` | Reads local append-only governance audit entries with filters (account, tool, status, date). |
|
|
409
|
+
| `get_pending_approvals` | Lists pending human-approval previews awaiting confirmation. |
|
|
410
|
+
| `list_expiring_approvals` | Highlights pending approvals nearing their TTL expiration. |
|
|
411
|
+
| `list_pending_client_approvals` | Lists approvals requiring explicit client sign-off when `REQUIRE_CLIENT_APPROVAL=true`. |
|
|
412
|
+
| `export_audit_log` | Exports filtered audit logs to JSON or CSV for compliance/client reporting. |
|
|
413
|
+
| `rotate_audit_log` | Archives older daily audit JSONL files into compressed zip archives per retention policy. |
|
|
414
|
+
|
|
415
|
+
---
|
|
416
|
+
|
|
417
|
+
### 10. `operations` Module (68 guarded write & governance tools — opt-in only)
|
|
418
|
+
|
|
419
|
+
**Hidden from `tools/list` whenever `READ_ONLY_MODE=true`.** Only exposed when `READ_ONLY_MODE=false` and `operations` (or `--preset full`) is enabled. Every mutation requires `dry_run=true` first (`approval_id` returned) before `dry_run=false`. See [Write Safety Guarantees by Family](docs/compatibility-matrix.md#5-write-safety-guarantees-by-family-operations-module) for exact `validateOnly`, `state_verifier`, and `revert_operation` coverage per family.
|
|
420
|
+
|
|
421
|
+
- **Campaigns & Budgets (13):** `create_campaign_budget`, `update_campaign_budget` *(optimistic locking + revert)*, `create_search_campaign`, `create_pmax_campaign`, `create_display_campaign`, `create_campaign_from_template`, `update_campaign`, `pause_campaign` *(optimistic locking + revert)*, `enable_campaign` *(optimistic locking + revert)*, `remove_campaign` *(optimistic locking)*, `update_campaign_geo_targets`, `update_campaign_schedule`, `copy_campaign`.
|
|
422
|
+
- **Ad Groups & Ads (11):** `create_ad_group`, `update_ad_group`, `pause_ad_group`, `enable_ad_group`, `remove_ad_group`, `create_responsive_search_ad`, `create_call_ad`, `update_ad`, `pause_ad`, `enable_ad`, `remove_ad`.
|
|
423
|
+
- **Keywords, Bids & Negatives (10):** `add_keywords_to_ad_group`, `update_keyword_bid` *(optimistic locking + revert)*, `pause_keyword` *(revert)*, `enable_keyword` *(revert)*, `remove_keyword`, `add_negative_keyword`, `add_negative_keywords_bulk`, `create_negative_keyword_list`, `attach_negative_keyword_list_to_campaign`, `add_account_negative_keywords` *(applies across Search, Shopping & PMax)*.
|
|
424
|
+
- **Audiences, Bid Modifiers & Customer Match (6):** `add_audience_to_ad_group`, `remove_audience_from_ad_group`, `update_bid_modifier`, `create_customer_match_list`, `add_customer_match_members` *(local SHA-256 hashing, zero raw PII in logs)*, `remove_customer_match_members`.
|
|
425
|
+
- **Assets, Extensions & Placements (8):** `create_sitelink_extension`, `create_callout_extension`, `create_structured_snippet_extension`, `create_call_extension`, `create_image_asset`, `link_asset_to_campaign`, `unlink_asset_from_campaign`, `exclude_placements` *(campaign or account level, websites & mobile apps, deduplicated up to 100)*.
|
|
426
|
+
- **PMax, Demand Gen, Experiments & Recommendations (8):** `create_pmax_asset_group`, `create_demand_gen_campaign`, `create_demand_gen_ad_group`, `create_experiment`, `schedule_experiment`, `end_experiment`, `apply_recommendation`, `dismiss_recommendation`.
|
|
427
|
+
- **Conversion Actions, Goals & Offline Uploads (8):** `create_conversion_action`, `update_conversion_action`, `pause_conversion_action`, `update_campaign_conversion_goal` *(optimistic locking + revert)*, `set_conversion_action_primary` *(optimistic locking + revert)*, `upload_click_conversions`, `upload_call_conversions`, `upload_conversion_adjustments`.
|
|
428
|
+
- **MCC Bulk & Write Governance (4):** `mcc_bulk_apply` *(multi-account guarded batch with per-item execution tracking & `retry_failed_from_approval_id` partial retry)*, `approve_operation`, `reject_operation`, `revert_operation`.
|
|
429
|
+
|
|
430
|
+
---
|
|
431
|
+
|
|
432
|
+
## MCP Prompts & Resources
|
|
433
|
+
|
|
434
|
+
Clients that support MCP Prompts and Resources automatically receive:
|
|
435
|
+
|
|
436
|
+
| Type | Identifier | Purpose |
|
|
437
|
+
| --- | --- | --- |
|
|
438
|
+
| **Prompt** | `analysis_profile_prompt` | Loads any Markdown + TOML analysis profile (`leads-audit`, `ecommerce-audit`, `agency-weekly`, or custom user profile) with reproducibility header and parameters. |
|
|
439
|
+
| **Prompt** | `google_ads_workflow` | Guided step-by-step Google Ads analysis workflow. |
|
|
440
|
+
| **Prompt** | `gaql_help` | GAQL query construction assistance and best practices. |
|
|
441
|
+
| **Prompt** | `monthly_client_review` | Structured monthly performance & optimization review prompt. |
|
|
442
|
+
| **Prompt** | `safe_campaign_change` | Guided `dry_run -> review diff -> approval_id -> execute` change workflow. |
|
|
443
|
+
| **Resource** | `agency://governance/status` | Live read-only snapshot of active guardrails, limits, and operator settings. |
|
|
444
|
+
| **Resource** | `gaql://reference` | Compact GAQL field & resource reference. |
|
|
445
|
+
| **Template** | `agency://docs/{domain}` | Embedded domain guides (campaigns, guardrails, reporting, offline conversions, Keyword Planner, etc.). |
|
|
446
|
+
| **Template** | `agency://tools/{tool_name}` | Tool-level usage documentation and safety notes. |
|
|
447
|
+
|
|
448
|
+
> **Multi-AI self-containment:** Critical workflows (analysis profiles, `dry_run` rules, currency/timezone metadata, truncation flags) are also exposed directly through tools so clients that ignore MCP Prompts/Resources work with zero loss of functionality.
|
|
449
|
+
|
|
450
|
+
---
|
|
451
|
+
|
|
452
|
+
## Customizable Analysis Profiles (Markdown + TOML)
|
|
453
|
+
|
|
454
|
+
Built-in profiles are packaged inside the wheel (`agency/builtin_profiles/` + `config/profiles/`) so they work even when installed via `pip`/`uvx` outside a git checkout:
|
|
455
|
+
- **`leads-audit`** (`.toml` + `.md`): Lead-gen Search audit covering conversion goals, primary vs. secondary separation, delivery, pacing, wasted search terms, and Quality Score.
|
|
456
|
+
- **`ecommerce-audit`** (`.toml` + `.md`): Ecommerce audit covering PMax asset groups/placements, Shopping SKU/brand ROAS & waste, conversion tracking, and budget pacing.
|
|
457
|
+
- **`agency-weekly`** (`.toml` + `.md`): Multi-account weekly executive review separated by currency with alerts and prioritized next actions.
|
|
458
|
+
|
|
459
|
+
**User customization:** Place `<profile-id>.toml` and/or `<profile-id>.md` in `GOOGLE_ADS_CONFIG_DIR/profiles/` to create custom profiles or override any built-in profile. TOML thresholds automatically merge over `alerts.json` defaults.
|
|
460
|
+
|
|
461
|
+
**Security boundary:** Profiles control analysis methodology, target KPIs, and report structure only. They **cannot** override `READ_ONLY_MODE`, `ALLOWED_CUSTOMER_IDS`, economic caps, or human approval requirements.
|
|
462
|
+
|
|
463
|
+
---
|
|
464
|
+
|
|
465
|
+
## CLI Commands & Scheduled Alerts
|
|
466
|
+
|
|
467
|
+
The lightweight CLI dispatcher (`google_ads_cli.py`) powers all subcommands without pre-importing the server or `.env` before managed profile initialization:
|
|
468
|
+
|
|
469
|
+
```bash
|
|
470
|
+
# 1. Start MCP server directly (stdio or streamable-http)
|
|
471
|
+
google-ads-mcp-server --transport stdio --demo --preset ecommerce
|
|
472
|
+
google-ads-mcp-server --transport streamable-http --host 127.0.0.1 --port 8000
|
|
473
|
+
|
|
474
|
+
# 2. Browser OAuth onboarding + client registration
|
|
475
|
+
google-ads-mcp-server connect --client claude-desktop --customer 1234567890 --preset leads
|
|
476
|
+
|
|
477
|
+
# 3. Register an existing profile or --demo in another desktop client
|
|
478
|
+
google-ads-mcp-server register --client codex --preset agency
|
|
479
|
+
google-ads-mcp-server register --client generic --demo
|
|
480
|
+
|
|
481
|
+
# 4. Preflight diagnostics (live or offline, human or JSON)
|
|
482
|
+
google-ads-mcp-server doctor
|
|
483
|
+
google-ads-mcp-server doctor --offline --json
|
|
484
|
+
|
|
485
|
+
# 5. Serve a managed profile directly (read-only enforced, uses saved or CLI preset)
|
|
486
|
+
google-ads-mcp-server --profile /path/to/profile.json serve --preset ecommerce
|
|
487
|
+
|
|
488
|
+
# 6. Scheduled alerts CLI (for cron, GitHub Actions, Slack/email scripts)
|
|
489
|
+
google-ads-mcp-server alerts --profile leads-audit --format markdown --fail-on-alerts
|
|
490
|
+
google-ads-mcp-server alerts --demo --profile leads-audit --format json
|
|
491
|
+
```
|
|
492
|
+
|
|
493
|
+
`alerts --fail-on-alerts` exits with code `2` whenever one or more threshold alerts fire.
|
|
494
|
+
|
|
495
|
+
---
|
|
496
|
+
|
|
497
|
+
## Data Accuracy, Truncation & Safety Architecture
|
|
498
|
+
|
|
499
|
+
- **Account time zone & closed days:** Reporting and diagnostic tools resolve date windows in each account's `customer.time_zone` (with `tzdata` on Windows) and exclude the current incomplete day by default (`complete_days_only=True`). Every response includes `currency_code`, `time_zone`, `queried_at_utc`, and `conversion_lag_warning` when the window ends within the last 3 days.
|
|
500
|
+
- **No silent truncation or false-positive absence alerts:** Bounded searches cap pagination at `GOOGLE_ADS_MAX_SEARCH_ROWS` (default `2000`) and propagate `truncated`, `totals_are_partial`, `truncated_queries`, `truncation_warning`, and `coverage_complete: false`. Absence-based alerts (`SMART_BIDDING_WITHOUT_EFFECTIVE_ACTIONS`, `PRIMARY_ACTION_NO_VOLUME`, `NO_RECENT_OFFLINE_UPLOADS`, `NO_APPROVED_BILLING_SETUP`) automatically downgrade to `insufficient_data` whenever their backing query is truncated (or an optional goal/summary query fails).
|
|
501
|
+
- **Strict multi-currency & multi-MCC isolation:** Agency dashboards never sum metrics across different currencies (`managed_totals_by_currency`), and dynamic `login-customer-id` routing lets one session switch cleanly between direct accounts and multiple MCCs (`RuntimeContext` + `GOOGLE_ADS_LOGIN_CUSTOMER_MAP` + `list_client_accounts`).
|
|
502
|
+
- **Loopback-only HTTP by default:** `streamable-http` defaults to `127.0.0.1` (including inside `Dockerfile`) and refuses to bind to non-loopback hosts (`0.0.0.0`, etc.) unless `MCP_HTTP_ALLOW_REMOTE=true` is explicitly set behind an authenticated HTTPS proxy.
|
|
503
|
+
- **PII & hygiene protection:** Audit logs redact sensitive payloads; offline conversion diagnostics and Customer Match never log raw PII; automated hygiene tests block tracked credentials or client data.
|
|
504
|
+
|
|
505
|
+
---
|
|
506
|
+
|
|
507
|
+
## Client Compatibility & Self-Hosted HTTP
|
|
508
|
+
|
|
509
|
+
- **Desktop `stdio` (primary v1.0 path):** Config generation and `stdio` MCP handshakes are automated for Claude Desktop, Claude Code, Codex, Antigravity, Gemini CLI, and generic desktop hosts (Cursor, VS Code, Cherry Studio, Cline, Kimi CLI). Desktop `.mcpb` bundling is **planned** (not yet built). See [Compatibility Matrix](docs/compatibility-matrix.md) for verified status per client, channel coverage, API boundaries, and per-family write guarantees.
|
|
510
|
+
- **Self-hosted Remote & Hosted Beta (`Streamable HTTP` + OAuth):**
|
|
511
|
+
- Single-user self-hosted mode via `google-ads-mcp-server --transport streamable-http` (loopback-only unless `MCP_HTTP_ALLOW_REMOTE=true` behind an authenticated HTTPS proxy).
|
|
512
|
+
- Multi-user OAuth gateway via `google-ads-mcp-server remote` supporting both static managed pilots (`MCP_REMOTE_WORKERS`) and **self-serve hosted onboarding** (`/connect` Google OAuth + PKCE, Fernet-encrypted SQLite profile store, lazy-spawning idle-evicting worker pool, per-user presets, and 1-click token revocation). See [Remote Pilot & Self-Serve Guide](docs/remote-pilot.md).
|
|
513
|
+
|
|
514
|
+
---
|
|
515
|
+
|
|
516
|
+
## Development & Documentation
|
|
517
|
+
|
|
518
|
+
- [Compatibility Matrix (AI Apps, Channels, API Limits, Write Guarantees)](docs/compatibility-matrix.md)
|
|
519
|
+
- [Guía rápida y playbooks por rol (Español)](docs/es/README.md) | [Guía de conexión (Español)](docs/connect.md)
|
|
520
|
+
- [Operational Design](DESIGN.md) | [Guardrails](docs/guardrails.md) | [Release Checklist](docs/release-checklist.md)
|
|
521
|
+
- [Roadmap v3 (Desktop Beta & Acceptance)](docs/roadmap-marketing-v3.md) | [Roadmap v2 & Technical Log](docs/roadmap-marketing-v2.md)
|
|
522
|
+
|
|
523
|
+
Run the full automated test suite:
|
|
524
|
+
|
|
525
|
+
```bash
|
|
526
|
+
pip install -e ".[dev]"
|
|
527
|
+
python -m pytest -q
|
|
528
|
+
```
|
|
529
|
+
|
|
530
|
+
## License
|
|
531
|
+
|
|
532
|
+
MIT. See [LICENSE](LICENSE).
|