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_accessible_customers	List customer IDs accessible to the configured credentials.
get_account_hierarchy	List accounts under a manager (MCC) account.
list_campaigns	List campaigns and their settings (no metrics).
get_campaign_performance	Campaign-level metrics (impressions, clicks, cost, conversions).
get_ad_group_performance	Ad group-level metrics.
get_keyword_performance	Keyword-level metrics.
run_gaql	Run a raw read-only GAQL SELECT query.

Prerequisites

You need Google Ads API credentials:

1. A developer token from the Google Ads API Center (Tools & Settings → API Center) on the manager account you'll authenticate with.
2. An OAuth2 client ID / client secret from a Google Cloud project with the Google Ads API enabled.
3. 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-ads Python library.
4. 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 values

Option B: environment variables

cp .env.example .env
# edit .env, then export the variables into your shell environment

Either 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-mcp

The 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 SELECT queries via GoogleAdsService.SearchStream. GAQL has no INSERT/UPDATE/DELETE syntax, so there is no way to mutate Google Ads data through these tools.
• Never commit google-ads.yaml or .env — both are gitignored. Treat your developer token, OAuth client secret, and refresh token as credentials.
• customer_id and entity IDs are validated as numeric before being interpolated into GAQL query strings.