Google Keyword Planner MCP Server

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

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

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.