Google Keyword Planner

io.github.afeezadebayoPublished by GitHub account afeezadebayov1.1.0Updated Oct 31, 2026

Keyword ideas, search volumes, CPC ranges, trends and forecasts from Google Ads Keyword Planner.

VerifiedSTDIODesktop onlyData & AnalyticsBusiness & Commerce

Overview

AI-generated overview

Local MCP server that pulls Google Ads Keyword Planner data — keyword ideas, search volumes, bids, trends and forecasts — into an assistant.

What you can do
  • Generate keyword ideas from seed keywords, a URL, keywords plus a URL, or a whole site, with volume, competition, bid ranges and trends
  • Get historical search volume and trends for up to 10,000 exact keywords, with close variants and a list of keywords with no data
  • Forecast impressions, clicks, cost, CTR and average CPC for keywords at a given max CPC over 1 to 365 days
  • Look up Google location IDs by place name and list targetable languages with codes and IDs
  • List the Google Ads accounts a login can access and check credentials, account, currency and defaults
When to use it
Useful for SEO, paid search and content planning when you want keyword research, volume checks or budget forecasts inside the chat instead of the Keyword Planner web UI. It suits users who already have a Google Ads account and can set up Google Ads API access.
Requirements
Runs locally as a Node.js process (npm install and build from source, or the Claude Desktop bundle). Needs an enabled Google Ads account and a Google Cloud project with the Google Ads API enabled and Basic access, plus an OAuth Desktop client. Required environment variables: GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET, GOOGLE_ADS_REFRESH_TOKEN and GOOGLE_ADS_CUSTOMER_ID; optional GOOGLE_ADS_LOGIN_CUSTOMER_ID, KEYWORD_PLANNER_DEFAULT_LANGUAGE and KEYWORD_PLANNER_DEFAULT_LOCATIONS. Network…
Before you install
The server holds OAuth credentials: GOOGLE_ADS_CLIENT_SECRET and GOOGLE_ADS_REFRESH_TOKEN grant access to your Google Ads account, so keep them in the client config and treat them as secrets. Obtaining Basic access requires brand verification and may require upgrading a free-trial billing account to a paid tier. Volumes are estimates and may be broader for accounts with little spend. Requests are rate limited and retried automatically.

Installation

In SourceWeft

  1. Open Google Keyword Planner 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 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."

Tools

ToolWhat it does
generate_keyword_ideasIdeas 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_volumeHistorical 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_keywordsImpressions, clicks, cost, CTR and average CPC for keywords at a given max CPC over 1 to 365 days.
find_locationsLook up Google location IDs by place name.
list_languagesList targetable languages with codes and IDs.
list_accessible_customersList the Google Ads accounts your login can access.
check_connectionConfirm 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:

    bash
    npm installGOOGLE_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)

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

Then add it to your client config:

json
{  "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:

bash
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

VariableRequiredNotes
GOOGLE_ADS_CLIENT_IDYesOAuth client (Desktop app). Its Cloud project needs Basic access.
GOOGLE_ADS_CLIENT_SECRETYes
GOOGLE_ADS_REFRESH_TOKENYesFrom npm run auth.
GOOGLE_ADS_CUSTOMER_IDYesThe account to query. Dashes are fine.
GOOGLE_ADS_LOGIN_CUSTOMER_IDNoYour manager account ID, if you access the account through one.
GOOGLE_ADS_API_VERSIONNoDefaults to v25. Change it when Google retires a version.
KEYWORD_PLANNER_DEFAULT_LANGUAGENoUsed when a request doesn't name a language.
KEYWORD_PLANNER_DEFAULT_LOCATIONSNoComma-separated names or IDs used when a request doesn't name locations.
GOOGLE_ADS_DEVELOPER_TOKENNoLegacy. 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

bash
npm installnpm run typechecknpm run buildnpm 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.

Source: README.md at commit df938df

Tools

0
SourceWeft started this package once in an isolated sandbox, without credentials, to list its tools. That failed: the package type cannot run in the sandbox.

Version history

1
  1. v1.1.0LatestOct 31, 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