Google Keyword Planner

Google Keyword Planner MCP 服务

一个 MCP 服务，让 Claude 和其他 MCP 客户端可直接访问 Google Ads Keyword Planner 数据：关键词建议、月均搜索量、竞争程度、首页出价范围、月度趋势，以及点击量和费用预测。

由 Afeez Adebayo 构建。采用 MIT 许可。

你可以这样询问

• “为尼日利亚的 在线会计软件 查找 100 个关键词建议，并按搜索量排序。”
• “查询英国和美国这 50 个关键词的搜索量及其趋势。”
• “从 https://example.com/pricing 提取关键词建议。”
• “预测这些精确匹配关键词在 30 天内以 ₦300 的最高 CPC 获得的点击量和费用。”

工具

工具	功能
generate_keyword_ideas	根据种子关键词、URL、关键词加 URL 或整个网站生成建议。返回月均搜索量、竞争程度、首页出价下限和上限、3 个月变化、整个时段（所示首月到末月）的变化，以及可选的月度搜索量。可按最低搜索量筛选，并按搜索量、竞争程度、出价或相关性排序。
get_search_volume	查询最多 10,000 个精确关键词的历史指标，包含近似变体，以及 Google 未返回数据的关键词列表。可选月份范围。
forecast_keywords	预测关键词在给定最高 CPC 和 1 至 365 天期限内的展示次数、点击次数、费用、CTR 和平均 CPC。
find_locations	按地点名称查找 Google 地点 ID。
list_languages	列出可定位的语言及其代码和 ID。
list_accessible_customers	列出你的登录账号可访问的 Google Ads 账号。
check_connection	确认凭据并显示账号、货币和默认设置。

地点和语言既可使用普通名称（"Nigeria"、"Lagos"、"English"），也可使用 Google ID。出价和费用以你的 Google Ads 账号货币显示。

所需条件

Keyword Planner 数据来自 Google Ads API。自 2026 年 9 月 9 日起，Google 不再使用开发者令牌：API 访问权限归属于拥有 OAuth 客户端的 Google Cloud 项目。你需要：

1. 一个 Google Ads 账号。 账号必须已启用，但不需要正在投放广告系列。管理账号可选。

2. 一个已启用 Google Ads API 的 Google Cloud 项目。 在 Google Cloud 控制台中创建项目并启用 Google Ads API。这样会获得测试访问权限，但该权限仅适用于测试账号。

3. 该项目的基本访问权限。 Explorer 访问权限不包含 Keyword Planner，因此你需要基本访问权限：

   • 配置 OAuth 同意屏幕（Google Auth Platform > Branding），并完成品牌验证。
   • 打开该项目的 Google Ads API Overview page 并申请基本访问权限。Google 会自动审核，通常在品牌验证完成后几分钟内即可完成。
   • 如果你的项目处于 Google Cloud 免费试用期，Google 可能会拒绝申请；将结算账号升级到付费层级即可解决此问题（Google Ads API 不会向你收费）。

4. 一个 OAuth 客户端 ID，类型为桌面应用，且位于同一项目中。将同意屏幕的发布状态设为In production，因为处于 Testing 状态的应用所获取的刷新令牌会在 7 天后过期。

5. 一个刷新令牌。 克隆此仓库并运行：

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

   打开显示的链接，使用可访问你 Ads 账号的 Google 账号登录，然后复制程序显示的刷新令牌。

安装

Claude Desktop（一键安装）

从最新版本下载 google-keyword-planner.mcpb 并打开。Claude Desktop 会提示你输入凭据，并安全地存储密钥。

任意 MCP 客户端（从源码安装）

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

然后将其添加到客户端配置中：

{
  "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"
      }
    }
  }
}

对于 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

配置

变量	必填	说明
GOOGLE_ADS_CLIENT_ID	是	OAuth 客户端（桌面应用）。其 Cloud 项目需要 Basic 访问权限。
GOOGLE_ADS_CLIENT_SECRET	是
GOOGLE_ADS_REFRESH_TOKEN	是	来自 npm run auth。
GOOGLE_ADS_CUSTOMER_ID	是	要查询的账户。可以包含连字符。
GOOGLE_ADS_LOGIN_CUSTOMER_ID	否	如果你通过经理账户访问该账户，请填写经理账户 ID。
GOOGLE_ADS_API_VERSION	否	默认为 v25。Google 停用某个版本时，请更改此值。
KEYWORD_PLANNER_DEFAULT_LANGUAGE	否	请求未指定语言时使用。
KEYWORD_PLANNER_DEFAULT_LOCATIONS	否	请求未指定地点时使用，以逗号分隔的名称或 ID。
GOOGLE_ADS_DEVELOPER_TOKEN	否	旧版配置。Google 已于 2026 年 9 月 9 日停用开发者令牌；只有设置此值时才会发送。

须知

• 搜索量是估算值。 Keyword Planner 会将搜索量四舍五入到一定范围，并合并相近的变体。广告支出较少或没有广告支出的账户可能会看到更宽泛的范围。
• 速率限制。 Keyword Planner 限制每分钟的请求次数。服务会自动重试触发速率限制的请求和服务器错误，并采用退避策略。
• 错误会说明解决方法。 常见问题（Cloud 项目只有 Test 访问权限、缺少经理账户 ID、刷新令牌已过期）会附带通俗易懂的解决说明。
• 隐私。 服务在你的计算机上运行，只与 Google 通信。凭据保存在 MCP 客户端的配置中。

开发

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

发布流程已自动化：更新 package.json 中的 version 并推送到 main，即可构建捆绑包、创建 GitHub 发布版本，并将项目列表发布到官方 MCP Registry。