google-ads-mcp
Provides read-only reporting tools for Google Ads, enabling listing campaigns, ad groups, keywords, account hierarchy, and running raw GAQL SELECT queries.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@google-ads-mcp what are my top campaigns by clicks this month?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
google-ads-mcp
A read-only MCP server for the Google Ads API. It exposes reporting tools (campaigns, ad groups, keywords, and raw GAQL queries) so an MCP client (Claude Code, Claude Desktop, etc.) can query your Google Ads account. There are no mutate/write tools — this server cannot change campaigns, budgets, or bids.
Tools
Tool | Description |
| List customer IDs accessible to the configured credentials. |
| List accounts under a manager (MCC) account. |
| List campaigns and their settings (no metrics). |
| Campaign-level metrics (impressions, clicks, cost, conversions). |
| Ad group-level metrics. |
| Keyword-level metrics. |
| Run a raw read-only GAQL |
Related MCP server: Google Ads MCP Reader
Prerequisites
You need Google Ads API credentials:
A developer token from the Google Ads API Center (Tools & Settings → API Center) on the manager account you'll authenticate with.
An OAuth2 client ID / client secret from a Google Cloud project with the Google Ads API enabled.
A refresh token for a user with access to the target account(s). See Google's OAuth desktop flow guide or run the helper script bundled with the
google-adsPython library.If you authenticate via a manager (MCC) account on behalf of a client account, its
login_customer_id.
Setup
# from the repo root
pip install -e .Configure credentials one of two ways:
Option A: YAML file
cp google-ads.yaml.example google-ads.yaml
# edit google-ads.yaml with your valuesOption B: environment variables
cp .env.example .env
# edit .env, then export the variables into your shell environmentEither google-ads.yaml in the current directory, or the GOOGLE_ADS_*
environment variables, will be picked up automatically. Set
GOOGLE_ADS_CONFIGURATION_FILE_PATH to point at a YAML file in a different
location if you'd prefer.
Running standalone
python -m google_ads_mcp
# or, after `pip install -e .`:
google-ads-mcpThe server communicates over stdio, per the MCP spec.
Registering with an MCP client
Claude Code (project-level .mcp.json, or claude mcp add):
{
"mcpServers": {
"google-ads": {
"command": "google-ads-mcp",
"env": {
"GOOGLE_ADS_CONFIGURATION_FILE_PATH": "/absolute/path/to/google-ads.yaml"
}
}
}
}Claude Desktop (claude_desktop_config.json): same mcpServers entry as
above.
Security notes
This server only issues GAQL
SELECTqueries viaGoogleAdsService.SearchStream. GAQL has noINSERT/UPDATE/DELETEsyntax, so there is no way to mutate Google Ads data through these tools.Never commit
google-ads.yamlor.env— both are gitignored. Treat your developer token, OAuth client secret, and refresh token as credentials.customer_idand entity IDs are validated as numeric before being interpolated into GAQL query strings.
Available Tools
7 toolsget_account_hierarchyB
List the accounts under a Google Ads manager (MCC) account, including nesting level.
Args: customer_id: The manager account's customer ID (10 digits, dashes optional).
Inputs: customer_id (required). Returns: result
get_ad_group_performanceA
Get ad group-level performance metrics (impressions, clicks, cost, conversions).
Args: customer_id: The Google Ads customer ID (10 digits, dashes optional). date_range: A GAQL date range literal, e.g. LAST_30_DAYS, LAST_7_DAYS, THIS_MONTH. campaign_id: Optional campaign ID to restrict results to a single campaign.
Inputs: customer_id (required), date_range, campaign_id. Returns: result
get_campaign_performanceA
Get campaign-level performance metrics (impressions, clicks, cost, conversions).
Args: customer_id: The Google Ads customer ID (10 digits, dashes optional). date_range: A GAQL date range literal, e.g. LAST_30_DAYS, LAST_7_DAYS, THIS_MONTH. campaign_id: Optional campaign ID to restrict results to a single campaign.
Inputs: customer_id (required), date_range, campaign_id. Returns: result
get_keyword_performanceA
Get keyword-level performance metrics (impressions, clicks, cost, conversions).
Args: customer_id: The Google Ads customer ID (10 digits, dashes optional). date_range: A GAQL date range literal, e.g. LAST_30_DAYS, LAST_7_DAYS, THIS_MONTH. campaign_id: Optional campaign ID to restrict results to a single campaign.
Inputs: customer_id (required), date_range, campaign_id. Returns: result
list_accessible_customersA
List the Google Ads customer IDs directly accessible to the configured credentials.
Inputs: no named parameters. Returns: result
list_campaignsA
List campaigns in an account with their basic settings (no performance metrics).
Args: customer_id: The Google Ads customer ID (10 digits, dashes optional). status: Optional filter - one of ENABLED, PAUSED, REMOVED.
Inputs: customer_id (required), status. Returns: result
run_gaqlA
Run a raw read-only GAQL SELECT query against the Google Ads API.
Use this for reporting needs not covered by the other tools. GAQL only supports SELECT statements, so this cannot modify any Google Ads data.
Args: customer_id: The Google Ads customer ID (10 digits, dashes optional). query: A GAQL SELECT query, e.g. "SELECT campaign.id, campaign.name FROM campaign WHERE campaign.status = 'ENABLED'".
Inputs: query (required), customer_id (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct resource or action: account listing, hierarchy, campaign listing, and performance at campaign, ad group, and keyword levels, plus a raw query fallback. There is no overlap or ambiguity between them.
All tool names follow a consistent verb_noun pattern (list_, get_, run_) and use snake_case throughout. The verbs accurately reflect the operation, and the nouns clearly indicate the target resource.
With 7 tools, the server is well-scoped for a read-only Google Ads reporting use case. Each tool serves a clear purpose, and the count is neither too sparse nor overwhelming.
The surface covers account enumeration, hierarchy, campaign listing, and performance at three key levels, plus a generic GAQL escape hatch. Minor gaps like structured ad group or keyword listing exist, but run_gaql can fill them, so no dead ends remain.
Related MCP Connectors
Read-only Google Search Console and Google Analytics for AI agents.
Read-only access for your AI to Search Console, GA4, Google Ads, Meta Ads and your store's sales.
Read-only Search Console analytics, URL inspection, indexing diagnostics, and sitemaps.
Amazon Ads, Seller Central, Vendor Central and AMC data for AI agents. Read-only by default.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceProvides read-only access to Google Ads account data including campaigns, ad groups, keywords, and performance reports. Enables querying via GAQL through an MCP interface.MIT
- AlicenseAqualityBmaintenanceA read-only MCP server for querying Google Ads data using GAQL, enabling AI assistants to safely read campaign performance, ad groups, and keywords.122MIT
- FlicenseNot gradedqualityDmaintenanceEnables read-only access to Google Analytics 4 and Google Search Console data, allowing users to run reports, query search analytics, and generate combined snapshots for reporting.-
- AlicenseNot gradedqualityBmaintenanceEnables read-only inspection of Google Ads accounts through MCP, including account inventory, reporting, metadata, change history, and safe GAQL queries.Apache 2.0