Google Ads MCP: GAQL queries, resources, recommendations, keyword ideas, change history. 11 tools.
Quick Install
Automated & IDE SetupCopy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.
One-click editor setup isn’t available for this listing yet — we don’t have a confirmed install command, and we’d rather show nothing than point your editor at the wrong package or host. Follow the project’s own setup instructions, linked above.
Manual Client & Custom JSON ConfigExpand JSON â–¾
No confirmed setup config for this listing yet. We only publish a config block when the install details come from the project itself — its README, its docs, or a verified owner. We haven’t found those for Google Ads MCP, and we’d rather show nothing than a guess you’d paste into your client. Follow the project’s own setup instructions for the current steps.
Documentation Overview
Google Ads MCP
Read-only MCP server for the Google Ads API. Eleven tools cover discovery, GAQL reporting, resource schema, recommendations, keyword planning and forecasts, and change history for any account reachable under a manager account (MCC). We run this server in production for every ads client. Read-only is enforced at three layers: no mutate or apply service imports, an SDK method allowlist, and a GAQL-starts-with-SELECT guard.
Install
Claude Code:
Codex:
Claude Desktop: download google-ads-mcp.mcpb from the latest GitHub release and open it.
Setup
This is the heaviest setup in the gallery: expect up to two days waiting on developer token approval. One set of credentials, rooted at a manager account (MCC), can read any customer account linked under it, so there is no per-client configuration beyond linking an account to the MCC.
- Google Ads developer token. Sign in at ads.google.com under your manager account, go to Tools and Settings, API Center, and apply for a developer token. A new token starts on the Explorer access level, which Google grants after a review that can take a few days; discovery, query and recommendation tools work there. Basic access (a separate application) is needed for higher quotas and may be needed for the keyword-planning tools.
- Google Cloud OAuth client. In a Google Cloud project, enable the Google Ads API, then create an OAuth client ID of type Desktop app under APIs and Services, Credentials. Note the client ID and client secret, and add the
https://www.googleapis.com/auth/adwordsscope to the OAuth consent screen. - Refresh token. Generate a refresh token once, as an admin user of the manager account, using Google's
oauth2ltool or thegenerate_user_credentials.pyexample shipped with thegoogle-adsPython library. Save the refresh token; it does not expire from normal use. - Login customer ID. Use the 10-digit customer ID of the manager account itself (no hyphens) as
GOOGLE_ADS_LOGIN_CUSTOMER_ID. Any client account accepts an invite to link under this manager account in its own Google Ads UI, after whichgoogle_ads_list_customer_clientssees it.
Tools (11)
| Tool | What it does |
|---|---|
google_ads_list_accessible_customers | List every customer_id the OAuth user has direct access to |
google_ads_list_customer_clients | Walk the MCC hierarchy and return every child account |
google_ads_query | Run a GAQL query against a specific customer account |
google_ads_describe_resource | Schema (fields, metrics, segments) for a GAQL resource |
google_ads_list_resources | Return the full catalog of GAQL resources |
google_ads_recommendations | Read Google's optimization recommendations for a customer account |
google_ads_keyword_ideas | Generate keyword ideas with search volume, competition and CPC estimates |
google_ads_keyword_historical_metrics | Historical monthly search-volume and competition metrics for specific keywords |
google_ads_keyword_forecast_metrics | Forecast KPIs for a proposed keyword plan |
google_ads_change_events | Audit trail of who changed what, last 30 days |
google_ads_change_status | Lightweight last-modified change tracker per resource |
Configuration
| Variable | Required | Purpose |
|---|---|---|
GOOGLE_ADS_DEVELOPER_TOKEN | yes | Google Ads API developer token from the Ads API Center |
GOOGLE_ADS_CLIENT_ID | yes | OAuth2 client_id for a Desktop-app credential |
GOOGLE_ADS_CLIENT_SECRET | yes | OAuth2 client_secret paired with the client_id |
GOOGLE_ADS_REFRESH_TOKEN | yes | Long-lived OAuth2 refresh_token for the adwords scope |
GOOGLE_ADS_LOGIN_CUSTOMER_ID | yes | 10-digit customer ID of the manager account (MCC), no hyphens |
GOOGLE_ADS_API_VERSION | no | Google Ads API version to target, default v25 |
GOOGLE_ADS_USE_PROTO_PLUS | no | Use proto-plus message types, default true |
GOOGLE_ADS_LOG_LEVEL | no | Python log level, default WARNING |
Reply shape
Every tool returns JSON with status (succeeded, partial, no_op), operation, summary, target, result, proof, warnings, recovery. Failures surface as a tool error whose text is google_ads_request_failed: <message> <hint>. proof.apiVersion names the Google Ads API version used. proof.microsConverted is set on google_ads_query. A partial status means the result hit its configured bound (max_rows, page_size or limit); recovery.nextAction says how to continue.
Limits
google_ads_query responses are capped at 64 MB per call by the Google Ads API; split large date ranges across calls. KeywordPlanIdeaService (keyword ideas, historical metrics, forecasts) is rate-limited to 1 query per second and may require Basic Access if you get a permission error on the Explorer tier. google_ads_change_events covers up to 30 days back; google_ads_change_status covers up to 14 days back. metrics.cost_micros and other *_micros fields are 1 unit = $0.000001; google_ads_query emits a matching *_units field alongside when convert_micros is true (the default).
Verify
Each release lists the package version, the .mcpb sha256 and the production commit it was derived from in CHANGELOG.md. CI runs the tests and a clean install of the built wheel on every push.
Privacy Policy
This server runs locally, on your machine, under your own credentials. It collects no personal data, contains no telemetry, stores nothing persistently, and talks only to the vendor API it wraps. No third party, including Scalably, receives your data. Contact: hello@scalably.io. Canonical copy: https://scalably.io/connector-privacy.html
License
MIT. Copyright Scalably.
Related MCP Servers
Reviews
No reviews yet — be the first to share how this listing worked for you.
Frequently Asked Questions about Google Ads MCP
AllMCPs Directory Badge
Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.
Badge Style:
Live Dynamic SVG Preview
Markdown (GitHub README)
[](https://allmcps.com/mcp/google-ads-mcp-2)HTML Embed
<a href="https://allmcps.com/mcp/google-ads-mcp-2"><img src="https://allmcps.com/api/badge/google-ads-mcp-2?style=directory" alt="Google Ads MCP on AllMCPs" /></a>Technical Specs & Signals
CategoryDeveloper Tools
27Quality signal: Emerging · 27/100How this signal is calculated ▾
Server availabilityNot measured
Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.
Verified ownership8/20
Documentation & tools11/30
Adoption & activity1/15
Community engagement0/10
A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.
Own this project?
This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge — proof is checked automatically, then reviewed by our team.
Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.
Claim & get free dofollowShare & Embed
Add our SVG badge (dark/light directory styles) or embeddable widget to your site.