Search Console Mcp

---

 Google Search Console
          │
          ▼
  search-console-mcp        ← runs on your machine, read-only
          │
          ▼
  Claude / Cursor / any MCP client
          │
          ▼
  "Why did my traffic drop?"

其他每个 Search Console MCP 服务都要求你创建 Google Cloud 项目、启用 API，还要处理服务账号 JSON 文件。这个服务不需要：

npx search-console-mcp-server login

浏览器会打开，你用 Google 登录即可完成。令牌由 Google 直接签发到你的设备，并且仅存储在 ~/.search-console-mcp/ 中——不会经过任何人的服务器。

	此服务	常见的 GSC MCP 配置
设置	npx … login，登录即可（约 30 秒）	创建 Google Cloud 项目、启用 API、创建 OAuth 凭据、下载 JSON，并在配置中指定该文件
运行环境	Node——使用 npx，无需安装任何内容	Python + uv/venv
是否能修改你的网站数据？	不可能——从设计上就只有只读权限	写入权限范围，只是“默认禁用”破坏性操作
分析	内置 10 项（健康检查、流量下滑、流量衰退、临界排名、关键词机会、关键词蚕食、标题/CTR 改写、更新与新建对比、内链、索引审计）	自行提供提示词

首次运行时会发生什么

$ npx search-console-mcp-server login
Opening your browser to sign in with Google…

Connected. Your Search Console is ready — tokens stored in
~/.search-console-mcp (this machine only).

只有在 Google 返回有效凭据且凭据已保存在本地后，浏览器才会打开设置页面。如果令牌交换或保存失败，页面会显示错误，而不是成功提示。无需克隆项目，也无需访问 Google Cloud 控制台。

---

使用体验

You:  Which of my pages are closest to page one?

Claude:  Three real opportunities, by impressions at stake:

  1. /pricing — "scoreboard app pricing" sits at position 11.2 with
     2,400 impressions/mo and almost no clicks. One position-group
     jump is worth ~90 clicks/mo. The title doesn't contain the
     query; start there.

  2. /templates/trivia — position 12.8 on "trivia scoreboard",
     1,100 impressions/mo. The page ranks but has no H2 matching
     the intent.

  3. /blog/keep-score-online — position 9.4, already page one on
     some days. It's cannibalizing with /features — run
     cannibalization_check before touching it.

（示例输出——展示形式和数据均为工具从你的真实数据中返回的内容。）

内置 SEO 分析工具

内置十种现成分析，作为 MCP 提示词提供，支持这些提示词的客户端可通过斜杠命令调用。每种分析都采用真实的 SEO 方法（阈值、原因分类、CTR 基准），并以按优先级排序的行动建议收尾，而不是简单倾倒数据：

提示词	你会得到什么
seo_checkup	对比上月趋势、最大变化项、快速见效机会，以及按影响 ÷ 工作量评分的前 3 项行动
traffic_drop	流量何时开始下滑、哪些页面受影响，以及原因判定：排名、CTR、索引、需求或季节性
traffic_decay	找出点击量逐月悄然流失的页面，并在流量崩跌前发现问题、确定优先级
striking_distance	按预估点击增长排序，列出排名在第 4–20 位的查询，并为每个页面提供一项改进建议
keyword_opportunities	一次性发掘所有增长机会：CTR 优化、首页排名提升、第二页排名提升和新兴需求
cannibalization_check	找出自家页面相互竞争的查询，确定胜出页面，为每种情况提供一项修复建议和恢复预估
title_ctr_rewrite	找出表现低于其排名水平的页面，并依据真实查询改写标题和元描述
refresh_vs_new	针对任意主题，依据现有内容覆盖情况给出单一结论：更新、整合、精简或新建
internal_links	提供来源 → 目标 → 锚文本的链接计划，并依据 Google 已发现的查询重叠情况说明理由
indexing_audit	检查站点地图，以及重要页面的索引状态，并按流量风险进行分类

设置

1. 登录（仅需一次）：

npx search-console-mcp-server login

2. 添加到你的 MCP 客户端：

Claude Code：

claude mcp add gsc -- npx -y search-console-mcp-server

Claude Desktop / Cursor / 其他客户端（mcpServers 配置）：

{
  "mcpServers": {
    "gsc": { "command": "npx", "args": ["-y", "search-console-mcp-server"] }
  }
}

3. 提问：

• “本月与上月相比，我的哪些页面点击量下降最多？”
• “列出排名在第 8–15 位且有实际展示量的查询词——哪些最接近首页？”
• “https://mysite.com/pricing 已编入索引了吗？如果没有，为什么？”
• “我获得了多少 Google Discover 流量？”

工具

工具	作用
list_properties	你的 GSC 资源（请先调用——会提供准确的 siteUrl 值）
query_search_analytics	按查询词、页面、日期、国家/地区和设备查看点击量 / 展示量 / 点击率 / 排名——支持筛选、分页和所有流量来源，包括 Google Discover
compare_periods	自动计算变化最大的项目：比较本期与上期，按页面或查询词计算差值，并按变化幅度排序
inspect_url	查看 Google 对某个 URL 的索引状态：是否已编入索引、原因、所选规范网址、上次抓取时间
inspect_urls	批量执行相同检查——单次调用最多检查 10 个 URL，适用于索引审核
list_sitemaps	查看已提交的网站地图及其状态

此工具从设计上就是只读的：它请求的 Google 权限范围（webmasters.readonly）无法修改你的资源、提交网站地图或更改任何内容——并非“默认禁用”，而是根本无法执行。

compare_periods 调用向你的模型提供的内容（模型无需自行计算日期）：

{ "key": "https://example.com/pricing",
  "current":  { "clicks": 1040, "impressions": 20502, "position": 6.4 },
  "previous": { "clicks": 1070, "impressions": 17176, "position": 5.8 },
  "deltaClicks": -30, "deltaImpressions": 3326, "deltaPosition": 0.6 }

隐私

• Google 权限范围为只读（webmasters.readonly）。
• 令牌保存在你机器上的 ~/.search-console-mcp/credentials.json，权限为 chmod 600。运行 npx search-console-mcp-server logout 可删除这些令牌。
• 不收集 MCP 使用遥测数据，也不通过代理——Search Console API 调用会从你的机器直接发送至 Google。成功登录后，浏览器会打开 Percy 设置页面，其 URL 中仅包含 MCP 来源和软件包版本；其中不包含凭据、授权码或资源数据。
• 想使用自己的 Google Cloud 项目？设置 SEARCH_CONSOLE_MCP_CLIENT_ID / SEARCH_CONSOLE_MCP_CLIENT_SECRET，即可使用你自己的项目。

常见问题 / 故障排除

无需我创建 Google 凭据，登录怎么能正常工作？ CLI 内置了 Google“桌面应用” OAuth 客户端——gcloud 和 GitHub 的命令行工具采用的也是这种受支持的模式。令牌仍由 Google 直接发放到你的机器（PKCE + localhost 回调）；它们不会经过我们的服务器。认证流程位于 src/auth.ts——可以自行查看。想要完全不使用共享凭据？使用你自己的凭据设置 SEARCH_CONSOLE_MCP_CLIENT_ID / SEARCH_CONSOLE_MCP_CLIENT_SECRET。

切换 Google 账号？ 再次运行 npx search-console-mcp-server login——Google 会显示账号选择器。

我的 MCP 客户端提示“未登录”？ 请使用与客户端相同的用户账号运行登录；凭据保存在 ~/.search-console-mcp/。

list_properties 中缺少某个资源。 已登录的 Google 账号需要在 Search Console 中至少拥有该资源的“受限”访问权限。

为什么没有昨天的数据？ Google Search Console 数据会延迟约 2–3 天。这是 Google 的限制，并非工具导致。历史数据可追溯约 16 个月。

撤销访问权限？ 运行 npx search-console-mcp-server logout 可删除本地令牌；访问 myaccount.google.com/permissions 可撤销授权本身。

开发

git clone https://github.com/sudomichael/search-console-mcp
cd search-console-mcp && npm install
npm run dev      # run from source
npm run build    # bundle to dist/ (no googleapis dependency)
npm test         # mocked login tests; no Google calls or credential writes

认证流程位于 src/auth.ts。如需核实上述任何隐私声明，请阅读源代码。

---

将研究成果转化为已发布的改进

MCP 始终免费。如果你希望有人协助改进某个特定页面，Percy 会研究你的 Search Console 证据，起草一项有针对性的改进，并将后续操作与已保存的工作关联起来。你可以在自己的 CMS 中审核并发布，然后验证改动并跟进结果。

Percy 是一个独立的付费工作区：免费使用 7 天，无需信用卡；之后如果继续使用，套餐价格为每月 29 美元起。它需要单独连接 Google；不会导入本地 MCP 凭据或对话。

---

采用 MIT 许可。欢迎提交问题和 PR。由 Percy 构建。