google-ads-kw-mcp

MCP server that exposes Google Ads keyword search volumes to AI agents — a free alternative to paid keyword-volume APIs, using the same KeywordPlanIdeaService that powers Google's Keyword Planner.

Why this instead of the official Google Ads MCP?

The official Google Ads MCP talks GAQL/REST and can't query KeywordPlanIdeaService. This server is complementary, not a duplicate — use it specifically for search volume, and the official one (or google-ads-write-mcp) for everything else.

Tools

get_keyword_volumes

Returns search volume data for an array of keywords.

Param	Type	Default	Description
keywords	list[str]	required	Max 20 keywords per call
customer_id	str	required	Google Ads account ID (no dashes)
country	str	"ES"	ISO country code (see list_keyword_countries)
language	str	"es"	Language code (es, en, fr, de, it, pt, nl, ja, zh, ru, ar)

Response:

[
  {
    "keyword": "surf lessons",
    "avg_monthly_searches": 480,
    "competition": "MEDIUM",
    "competition_index": 38,
    "low_top_of_page_bid_micros": 206702,
    "high_top_of_page_bid_micros": 980973
  }
]

list_keyword_countries

Returns the 20 supported countries (ISO code → name).

Setup

You need a Google Ads developer token (Standard Access is enough) and an OAuth client authorized against your Google Ads MCC/account. If you already have a google-ads.yaml from the Google Ads API client library, you can adapt its client_id/client_secret/refresh_token into the JSON format below.

1. Install dependencies:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   

2. Create ~/.config/google-ads-mcp/credentials.json:

   {
     "client_id": "...",
     "client_secret": "...",
     "refresh_token": "..."
   }
   

MCP client configuration

{
  "mcpServers": {
    "google-ads-kw": {
      "command": "/path/to/.venv/bin/python3",
      "args": ["/path/to/google-ads-kw-mcp/server.py"],
      "env": {
        "GOOGLE_ADS_CREDENTIALS_PATH": "~/.config/google-ads-mcp/credentials.json",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "<your developer token>",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "<your MCC customer id, no dashes>"
      }
    }
  }
}

Env var	Purpose
GOOGLE_ADS_CREDENTIALS_PATH	Path to the credentials JSON (default: ~/.config/google-ads-mcp/credentials.json)
GOOGLE_ADS_DEVELOPER_TOKEN	Your Google Ads developer token
GOOGLE_ADS_LOGIN_CUSTOMER_ID	Your MCC/login customer ID, no dashes

Limits

• Max 20 keywords per call (API limit).
• Long-tail keywords may return avg_monthly_searches: 0 if Google Ads doesn't have enough data.
• Free quota is generous (~15,000 ops/day for standard accounts) — plenty for this use case.

License

MIT — see LICENSE.