Google Ads MCP

io.scalablyPublished by scalably.iov1.0.1Updated Oct 24, 2026

Google Ads MCP: GAQL queries, resources, recommendations, keyword ideas, change history. 11 tools.

VerifiedSTDIODesktop onlyWeb Search & ScrapingData & AnalyticsBusiness & Commerce

Overview

AI-generated overview

Read-only local MCP server for the Google Ads API, letting an assistant query ad accounts, inspect resources, read recommendations and plan keywords.

What you can do
List accessible customer accounts and walk the manager account hierarchy to find child accounts. Run GAQL queries against a specific account, with micros-to-units conversion. Browse the GAQL resource catalog and describe a resource's fields, metrics and segments. Read Google's optimization recommendations for an account. Generate keyword ideas, historical monthly metrics and forecasts for a keyword plan. Review change history and last-modified status per resource.
When to use it
Use it when an assistant should answer questions about Google Ads performance, pull campaign or cost reports with GAQL, review optimization recommendations, or research keywords, across accounts linked under one manager account. It suits read-only analysis and reporting, not campaign edits.
Requirements
Local process run with uvx from the PyPI package (or the Claude Desktop .mcpb bundle), so Python tooling is needed. Requires a Google Ads developer token (approval can take days), a Google Cloud OAuth Desktop-app client ID and secret, a refresh token for the adwords scope, and the 10-digit manager account customer ID in GOOGLE_ADS_LOGIN_CUSTOMER_ID. Optional: GOOGLE_ADS_API_VERSION, GOOGLE_ADS_USE_PROTO_PLUS, GOOGLE_ADS_LOG_LEVEL.
Before you install
Requires long-lived OAuth and developer-token credentials (GOOGLE_ADS_CLIENT_SECRET, GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_ADS_REFRESH_TOKEN) that grant read access to every account linked under the manager account; store them carefully. The README states it is read-only, enforced by no mutate imports, an SDK allowlist and a SELECT-only GAQL guard, but that is the vendor's claim. Queries and keyword requests go to Google.

Installation

In SourceWeft

  1. Open Google Ads MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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:

bash
claude mcp add google-ads \  -e GOOGLE_ADS_DEVELOPER_TOKEN=your-token \  -e GOOGLE_ADS_CLIENT_ID=your-client-id \  -e GOOGLE_ADS_CLIENT_SECRET=your-client-secret \  -e GOOGLE_ADS_REFRESH_TOKEN=your-refresh-token \  -e GOOGLE_ADS_LOGIN_CUSTOMER_ID=1234567890 \  -- uvx scalably-google-ads-mcp

Codex:

bash
codex mcp add google-ads \  --env GOOGLE_ADS_DEVELOPER_TOKEN=your-token \  --env GOOGLE_ADS_CLIENT_ID=your-client-id \  --env GOOGLE_ADS_CLIENT_SECRET=your-client-secret \  --env GOOGLE_ADS_REFRESH_TOKEN=your-refresh-token \  --env GOOGLE_ADS_LOGIN_CUSTOMER_ID=1234567890 \  -- uvx scalably-google-ads-mcp

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.

  1. 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.
  2. 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/adwords scope to the OAuth consent screen.
  3. Refresh token. Generate a refresh token once, as an admin user of the manager account, using Google's oauth2l tool or the generate_user_credentials.py example shipped with the google-ads Python library. Save the refresh token; it does not expire from normal use.
  4. 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 which google_ads_list_customer_clients sees it.

Tools (11)

ToolWhat it does
google_ads_list_accessible_customersList every customer_id the OAuth user has direct access to
google_ads_list_customer_clientsWalk the MCC hierarchy and return every child account
google_ads_queryRun a GAQL query against a specific customer account
google_ads_describe_resourceSchema (fields, metrics, segments) for a GAQL resource
google_ads_list_resourcesReturn the full catalog of GAQL resources
google_ads_recommendationsRead Google's optimization recommendations for a customer account
google_ads_keyword_ideasGenerate keyword ideas with search volume, competition and CPC estimates
google_ads_keyword_historical_metricsHistorical monthly search-volume and competition metrics for specific keywords
google_ads_keyword_forecast_metricsForecast KPIs for a proposed keyword plan
google_ads_change_eventsAudit trail of who changed what, last 30 days
google_ads_change_statusLightweight last-modified change tracker per resource

Configuration

VariableRequiredPurpose
GOOGLE_ADS_DEVELOPER_TOKENyesGoogle Ads API developer token from the Ads API Center
GOOGLE_ADS_CLIENT_IDyesOAuth2 client_id for a Desktop-app credential
GOOGLE_ADS_CLIENT_SECRETyesOAuth2 client_secret paired with the client_id
GOOGLE_ADS_REFRESH_TOKENyesLong-lived OAuth2 refresh_token for the adwords scope
GOOGLE_ADS_LOGIN_CUSTOMER_IDyes10-digit customer ID of the manager account (MCC), no hyphens
GOOGLE_ADS_API_VERSIONnoGoogle Ads API version to target, default v25
GOOGLE_ADS_USE_PROTO_PLUSnoUse proto-plus message types, default true
GOOGLE_ADS_LOG_LEVELnoPython 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: [email protected]. Canonical copy: https://scalably.io/connector-privacy.html

License

MIT. Copyright Scalably.

Source: README.md at commit 2c40bbb

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.0.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts