Skip to main content
Glama
Google Keyword Planner MCP Server

Google Keyword Planner MCP Server

by afeezadebayo

Google Keyword Planner MCP server

An MCP server that gives Claude and other MCP clients direct access to Google Ads Keyword Planner data: keyword ideas, average monthly searches, competition, top-of-page bid ranges, monthly trends and click and cost forecasts.

Built by Afeez Adebayo. MIT licensed.

What you can ask

  • "Find 100 keyword ideas for online accounting software in Nigeria, sorted by search volume."

  • "Get search volume for these 50 keywords in the UK and US, with their trends."

  • "Pull keyword ideas from https://example.com/pricing."

  • "Forecast clicks and cost for these exact-match keywords at a ₦300 max CPC for 30 days."

Related MCP server: Google Ads MCP Server

Tools

Tool

What it does

generate_keyword_ideas

Ideas from seed keywords, a URL, keywords plus a URL, or a whole site. Returns average monthly searches, competition, low and high top-of-page bids, 3-month change, change across the period (first to last month shown), and optional monthly volumes. Filter by minimum volume and sort by searches, competition, bid or relevance.

get_search_volume

Historical metrics for up to 10,000 exact keywords, with close variants and a list of keywords Google returned no data for. Optional month range.

forecast_keywords

Impressions, clicks, cost, CTR and average CPC for keywords at a given max CPC over 1 to 365 days.

find_locations

Look up Google location IDs by place name.

list_languages

List targetable languages with codes and IDs.

list_accessible_customers

List the Google Ads accounts your login can access.

check_connection

Confirm credentials and show the account, currency and defaults.

Locations and languages accept plain names ("Nigeria", "Lagos", "English") as well as Google IDs. Bids and costs are shown in your Google Ads account currency.

What you need

Keyword Planner data comes from the Google Ads API. Since 9 September 2026, Google no longer uses developer tokens: API access belongs to the Google Cloud project that owns your OAuth client. You need:

  1. A Google Ads account. It must be enabled, but it doesn't need running campaigns. A manager account is optional.

  2. A Google Cloud project with the Google Ads API enabled. In the Google Cloud console, create a project and enable the Google Ads API. This gives Test access, which only works with test accounts.

  3. Basic access for that project. Keyword Planner isn't included in Explorer access, so you need Basic access:

    • Configure the OAuth consent screen (Google Auth Platform > Branding) and complete brand verification.

    • Open the Google Ads API Overview page for the project and apply for Basic access. Google reviews it automatically, usually within minutes of brand verification.

    • If your project is on the Google Cloud free trial, Google may reject the application; upgrading the billing account to a paid tier fixes this (you won't be charged for the Google Ads API).

  4. An OAuth client ID of type Desktop app, in the same project. Set the consent screen's publishing status to In production, because refresh tokens from apps in Testing status expire after 7 days.

  5. A refresh token. Clone this repository and run:

    npm install
    GOOGLE_ADS_CLIENT_ID=your-client-id GOOGLE_ADS_CLIENT_SECRET=your-secret npm run auth

    Open the printed link, sign in with the Google account that can access your Ads account, and copy the refresh token it prints.

Install

Claude Desktop (one click)

Download google-keyword-planner.mcpb from the latest release and open it. Claude Desktop asks for your credentials and stores the secrets securely.

Any MCP client (from source)

git clone https://github.com/afeezadebayo/google-keyword-planner-mcp.git
cd google-keyword-planner-mcp
npm install && npm run build

Then add it to your client config:

{
  "mcpServers": {
    "google-keyword-planner": {
      "command": "node",
      "args": ["/path/to/google-keyword-planner-mcp/server/index.js"],
      "env": {
        "GOOGLE_ADS_CLIENT_ID": "...",
        "GOOGLE_ADS_CLIENT_SECRET": "...",
        "GOOGLE_ADS_REFRESH_TOKEN": "...",
        "GOOGLE_ADS_CUSTOMER_ID": "123-456-7890",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "",
        "KEYWORD_PLANNER_DEFAULT_LANGUAGE": "English",
        "KEYWORD_PLANNER_DEFAULT_LOCATIONS": "Nigeria"
      }
    }
  }
}

For Claude Code:

claude mcp add google-keyword-planner \
  -e GOOGLE_ADS_CLIENT_ID=... -e GOOGLE_ADS_CLIENT_SECRET=... \
  -e GOOGLE_ADS_REFRESH_TOKEN=... -e GOOGLE_ADS_CUSTOMER_ID=123-456-7890 \
  -- node /path/to/google-keyword-planner-mcp/server/index.js

Configuration

Variable

Required

Notes

GOOGLE_ADS_CLIENT_ID

Yes

OAuth client (Desktop app). Its Cloud project needs Basic access.

GOOGLE_ADS_CLIENT_SECRET

Yes

GOOGLE_ADS_REFRESH_TOKEN

Yes

From npm run auth.

GOOGLE_ADS_CUSTOMER_ID

Yes

The account to query. Dashes are fine.

GOOGLE_ADS_LOGIN_CUSTOMER_ID

No

Your manager account ID, if you access the account through one.

GOOGLE_ADS_API_VERSION

No

Defaults to v25. Change it when Google retires a version.

KEYWORD_PLANNER_DEFAULT_LANGUAGE

No

Used when a request doesn't name a language.

KEYWORD_PLANNER_DEFAULT_LOCATIONS

No

Comma-separated names or IDs used when a request doesn't name locations.

GOOGLE_ADS_DEVELOPER_TOKEN

No

Legacy. Google retired developer tokens on 9 September 2026; it's only sent if you set it.

Good to know

  • Volumes are estimates. Keyword Planner rounds search volumes into ranges and groups close variants. Accounts with little or no ad spend may see broader ranges.

  • Rate limits. Keyword Planner allows a limited number of requests per minute. The server retries rate-limit and server errors automatically with back-off.

  • Errors explain the fix. Common problems (a Cloud project with only Test access, a missing manager account ID, an expired refresh token) come back with a plain-English explanation of how to fix them.

  • Privacy. The server runs on your machine and talks only to Google. Credentials stay in your MCP client's config.

Development

npm install
npm run typecheck
npm run build
npm test   # runs every tool against a local mock of the Google Ads API

Releases are automated: bumping version in package.json and pushing to main builds the bundle, creates a GitHub release and publishes the listing to the official MCP Registry.

Available Tools

7 tools
check_connectionCheck connectionA
Read-onlyIdempotent

Check that credentials work and show the configured account, API version, currency and defaults.

Inputs: no named parameters.

find_locationsFind location IDsA
Read-onlyIdempotent

Search Google's geo targets by name to get location IDs for countries, regions, cities and more.

Inputs: names (required), locale, country_code.

forecast_keywordsForecast clicks and costA
Read-onlyIdempotent

Forecast impressions, clicks, cost, CTR and average CPC for a set of keywords over a future period, using Keyword Planner's forecasting. Useful for budgeting a paid search campaign.

Inputs: max_cpc (required), keywords (required), days, network, +2 more.

generate_keyword_ideasGenerate keyword ideasA
Read-onlyIdempotent

Get keyword ideas from Keyword Planner using seed keywords, a page URL, a whole site, or keywords plus a URL. Returns each idea's average monthly searches, competition, top-of-page bid range, 3-month change, change across the period (first to last month), and monthly volumes.

Inputs: url, site, limit, network, +7 more.

get_search_volumeGet search volume and metricsA
Read-onlyIdempotent

Get historical Keyword Planner metrics for specific keywords: average monthly searches, monthly volumes, competition, top-of-page bid range and trends. Use this to check exact keywords rather than discover new ones. Close variants that Google groups together are listed.

Inputs: keywords (required), network, language, end_month, +3 more.

list_accessible_customersList Google Ads accountsA
Read-onlyIdempotent

List the Google Ads customer IDs the signed-in user can access. Use it to find the right GOOGLE_ADS_CUSTOMER_ID.

Inputs: no named parameters.

list_languagesList languagesA
Read-onlyIdempotent

List the languages Keyword Planner can target, with their codes and IDs.

Inputs: filter.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct capability: connectivity check, keyword discovery, exact-metric lookup, forecasting, geo lookup, language listing, and account listing. The only potential overlap is generate_keyword_ideas vs get_search_volume, but the descriptions explicitly frame one as discovery and the other as exact-keyword verification, so an agent can reliably choose.

    Naming Consistency5/5

    All seven names use consistent snake_case verb_noun structure (check_connection, generate_keyword_ideas, get_search_volume, forecast_keywords, find_locations, list_languages, list_accessible_customers). The verbs are descriptive and predictable throughout.

    Tool Count5/5

    Seven tools is well-scoped for a Keyword Planner integration, covering auth/config, discovery, metrics, forecasting, and the lookup helpers needed to use the main tools. No tool feels redundant or padded.

    Completeness4/5

    The surface covers the core Keyword Planner lifecycle: keyword discovery, exact metrics, forecasting, geo targeting, language targeting, and customer-ID discovery plus a connectivity check. Minor gaps exist, such as no tool for browsing keyword categories or filtering ideas by category/network settings, but core workflows are not blocked.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides SEO automation with tools for keyword research, SERP analysis, and competitor analysis through Google Ads API integration, enabling AI assistants to access these capabilities via MCP.
      50
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with Google Ads through secure OAuth authentication to discover keyword ideas, analyze historical search metrics, and generate forecasts for advertising campaigns. Built as a Next.js application with encrypted credential storage and rate limiting.
      1
      Apache 2.0
    • A
      license
      B
      quality
      C
      maintenance
      Enables comprehensive Google Ads campaign management and analysis through natural language, including performance metrics, keyword optimization, budget management, and custom GAQL queries.
      100
      17
      MIT