search-console-mcp

面向 Google Search Console 的 MCP 服务器，它将官方 Search Console API 以工具的形式提供给 AI 代理使用。

它的重点是 搜索效果和索引健康度——按查询、页面、国家/地区、设备或日期查询点击量、展示量、CTR 和排名，检查某个 URL 是否被索引以及未被索引的原因，并管理账号下的站点地图和资源。

它不会做的事情： 不请求对 URL 进行（重新）索引——这个独立的 Indexing API 只支持招聘信息页面和直播页面；不进行资源所有权验证（所有者必须将服务账号添加到每个资源中）；也不涉及 Google Analytics 数据（那是另一个无关的 Analytics Data API）。

删除操作是可选的（opt-in）。 只有当设置了 GOOGLE_SEARCH_CONSOLE_ALLOW_DESTRUCTIVE 时，delete_sitemap 和 delete_site 才会被注册——请参阅 Configuration。

Install

claude mcp add search-console \
  -e GOOGLE_SERVICE_ACCOUNT_KEY_PATH=/path/to/service-account.json \
  -e GOOGLE_SEARCH_CONSOLE_SITE_URL=https://example.com/ \
  -- npx -y @orellbuehler/search-console-mcp

-e 标志必须放在 -- 分隔符之前；-- 后面的内容会传给服务器进程执行，而不会被当作配置来读取。

Related MCP server: Google Search Console MCP Server

获取服务账号密钥

1. 在 Google Cloud console 中选择或创建一个项目，并启用 Google Search Console API。

2. 进入 IAM 与监管 → 服务账号 → 创建服务账号。可以跳过“授予访问权限”的可选步骤——Search Console 的权限是单独授予的，不通过 Cloud IAM 角色。

3. 打开新建的服务账号，进入 Keys 标签页，选择 Add key → Create new key → JSON。该文件只能下载一次，之后无法再次获取。

4. 在 Search Console 中打开资源，进入 Settings → Users and permissions → Add user，权限 并粘贴服务账号的邮箱地址（name@project-id.iam.gserviceaccount.com）。请授予：

   • 对于（analytics、sitemaps、URL inspection）等读取工具，授予 Restricted 或 Full 权限

   • 对于 submit_sitemap 和 delete_sitemapal，授予 Full 权限

5. 对服务器需要看到的每个资源重复第 4 步——服务账号无法自行验证资源所有权。

6. 将 GOOGLE_SERVICE_ACCOUNT_KEY_PATH 指向下载的 JSON 文件。

请像对待密码一样对待 JSON 密钥——它携带你授予的所有权限，没有第二道验证在前面。应将其放在仓库之外，并考虑使用 chmod 600。

配置

在该表中，GOOGLE_SERVICE_ACCOUNT_KEY_PATH 或 GOOGLE_SERVICE_ACCOUNT_KEY 为必须提供之一（即二者之一），其余变量视为可选。

资源既可以标识为 URL-prefix property（如 https://example.com/，协议和结尾斜线都很重要——http://example.com/ 和 http://example.com/ 是不同的资源——就必须注意两端都要写全）也可以标识为 domain property（如 sc-domain:example.com），后者包含所有子域和协议。请使用与资源在 Search Console 中被添加时一致的形式；你可以通过 list_sites 查看确切的字符串。

与 Claude Code 配套使用

{
  "mcpServers": {
    "search-console": {
      "command": "npx",
      "args": ["-y", "@orellbuehler/search-console-mcp"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY_PATH": "/path/to/service-account.json",
        "GOOGLE_SEARCH_CONSOLE_SITE_URL": "https://example.com/"
      }
    }
  }
}

示例提示词

• “我这个月有哪些热门搜索查询？”

• “哪些页面从 Google 获得最多的点击，与之前 28 天相比有什么变化？”

• “显示包含‘pricing’且我们排在较差位置（如 10 名开外）的查询——这些是快速见效的候选项。”

• “我们的流量中移动端与桌面端各占多少？”

• “画出最近三个月中每天的点击量和展示量趋势图。”

• “我们有没有被展示但几乎没有点击的国家？”

• “https://example.com/blog/launch 是被索引了吗？如果没有，为什么？”

• “列出我们的 sitemap，告诉我哪些有错误或警告。”

• “旧站点改版后，重新提交一次 sitemap。”

• “哪些针对‘mcp server’排名的页面之间存在竞争？”

• “对比本季度Discover 流量与常规搜索流量的表现。”

工具

搜索效果分析

站点地图

站点

URL 检查

注意事项

• 效果数据约有 2–3 天的延迟。 便捷工具默认把日期范围结束于 3 天前，而 data_state: "all" 会包含最新但可能不完整的数据。

• 数据保留 16 个月。 查询更早的数据不会返回任何行。

• 隐私过滤机制。 稀疏查询对应的行会被隐藏，因此按查询维度汇总会低于真实总数据；不带维度进行查询可以获得精确的总量。

• 单次调用最多 25,000 行。 需要用 start_row 分页；当返回的行数小于 row_limit 时，说明是最后一页。

• URL inspection 配额大约是每个资源每天 2,000 次调用、每分钟 600 次——应选择性地检查 URL，而不要批量执行。

• hour 维度必须用 data_state: "hourly_all"，并且只能覆盖最近约 10 天。

• 你的搜索数据会转移到 LLM——工具返回的一切都会成为模型上下文，因此不要接入任何不允许离开你环境的资源。

开发

npm install
npm run build         # tsc -p tsconfig.build.json -> dist/
npm test              # vitest run
npm run lint          # eslint src
npm run typecheck     # tsc --noEmit
npm run format        # prettier --write .

用真实资源基于构建后的 server 做冒烟测试：

GOOGLE_SERVICE_ACCOUNT_KEY_PATH=/path/to/service-account.json \
GOOGLE_SEARCH_CONSOLE_SITE_URL=https://example.com/ \
npx @modelcontextprotocol/inspector node dist/index.js

CI / 发布

CI 在 Node.js 20 和 22 上运行 format:check、lint、typecheck、test 和 build。发布通过 GitHub release 进行，并使用 npm trusted publishing（OIDC，无需 token）：

npm version patch
git push --follow-tags
gh release create "v$(node -p "require('./package.json').version")" --generate-notes

License

MIT © Orell Bühler