Tag Pilot Search Console

Tag Pilot Search Console MCP

一个免费的、只读Model Context Protocol 服务，适用于 Google Search Console。向 Claude、Cursor 或任何 MCP 客户端询问自然搜索情况：按查询或页面查看点击次数、 展示次数、点击率和排名，比较两个时期的变化，寻找 SEO 机会，查看某个 URL 在 Google 中的索引状态，以及查看 站点地图。

**无需设置 Google Cloud，也无需复制 API 密钥。**你不需要 GCP 项目、OAuth 客户端、 服务账号或 gcloud。添加服务、提出问题，然后在浏览器中批准一次即可。

claude mcp add search-console -- npx -y @tagpilot/search-console-mcp

开始使用

1. 在你的 AI 客户端中安装（见下文）。无需配置。
2. 提出问题，例如 “本月哪些查询的点击次数下降最多？” 首次使用时会打开 浏览器窗口（或者 AI 会显示链接和类似 ABCD-1234 的代码）：
   • 登录你的免费 Tag Pilot 账号，或创建一个；
   • 确认代码匹配，然后批准这台电脑；
   • 使用有权查看 Search Console 资源的 Google 账号登录，并允许只读的 Search Console 访问权限。
3. 再次提问。连接完成；这台电脑会显示在 Search Console MCP 页面的已连接设备下。

已经在使用 Tag Pilot GA4 MCP？这是一个独立的服务，有自己的连接 （以及单独的 Google 授权），因此你可以安装其中一个或两者都安装。

安装

客户端	方式
Claude Desktop	下载扩展并打开（无需 Node.js）
Claude Code	claude mcp add search-console -- npx -y @tagpilot/search-console-mcp
Cursor	添加到 Cursor，或使用下方的 mcp.json
VS Code	在 VS Code 中安装
Windsurf、Zed、……	命令 npx，参数 ["-y", "@tagpilot/search-console-mcp"]（stdio）
Gemini CLI	克隆仓库，然后运行 gemini extensions install ./ga4-mcp/packages/search-console-mcp

除 Claude Desktop 扩展外，其他方式都通过 npx 运行 npm 包，因此需要 Node.js 18 或更高版本。在 MCP Registry 中，该服务的名称为 io.github.tagpilot/search-console-mcp。

Claude Desktop 配置文件（claude_desktop_config.json）、Cursor（~/.cursor/mcp.json）及 类似客户端：

{
  "mcpServers": {
    "search-console": {
      "command": "npx",
      "args": ["-y", "@tagpilot/search-console-mcp"]
    }
  }
}

**无头环境和 CI：**如果没有人可以在浏览器中批准，请在 Search Console MCP 页面创建一个 gsc:mcp 密钥，并在服务的环境中设置 TAGPILOT_API_KEY=tpk_…。这样会跳过设备连接步骤，只显示 Google 登录链接。

连接方式以及 Tag Pilot 能看到的内容

流程与 GA4 MCP 相同（采用 RFC 8628 风格的设备连接方式，类似于 gh auth login）：你可以通过任何设备上的任何浏览器完成连接，也可以在 SSH、容器或 WSL 环境中使用，因为本机不会有任何进程监听端口。

• Search Console 数据会从你的机器直接发送到 Google （www.googleapis.com/webmasters/v3、searchconsole.googleapis.com），绝不会经过 Tag Pilot。
• Tag Pilot 只负责中转令牌交换。 它会将 Tag Pilot 的 Google OAuth 客户端凭据添加到 Google 的令牌端点，并返回 Google 的响应。它不会存储任何 Google 令牌，也绝不会记录这些令牌；它最多只会保存一次性登录码 10 分钟，而没有保留在你机器上的 PKCE 验证码，这个登录码毫无用处。
• 只读。 唯一请求的 Google 权限范围是 webmasters.readonly。这些工具都无法更改 Search Console 中的任何内容（不能提交站点地图，也不能删除内容）。
• 你的凭据会保留在本机，存放于 ~/.config/tagpilot/search-console-mcp/device.json（仅你本人可读取）。
• 断开连接： 在 Search Console MCP 页面撤销设备，运行 npx -y @tagpilot/search-console-mcp logout，并在 myaccount.google.com/permissions 中移除该应用的访问权限。

工具

所有工具均为只读。site_url 是 list_sites 显示的完整资源标识： 域名资源的格式为 sc-domain:example.com，网址前缀资源则带有末尾斜杠 （https://www.example.com/）。

工具	功能
list_sites	列出你有权读取的资源（域名和网址前缀）及其权限级别。请从这里开始。
search_analytics	按 date、hour、query、page、country、device、searchAppearance 统计点击次数、展示次数、CTR 和排名；支持筛选条件、搜索类型（网页、图片、视频、新闻、Discover、Google News）、数据状态、聚合方式和分页（每次调用最多返回 25,000 行）。
compare_periods	按查询词或网页比较两个时段：显示两个时段的数据、差值、新增／流失行以及资源总计。默认比较最近 28 天与此前 28 天。
find_opportunities	Tag Pilot 分析。 low_ctr：展示次数多但 CTR 不到该排名典型 CTR 一半的首页结果行。striking_distance：平均排名约为 5–20 且展示次数足够的结果行。
inspect_url	网址检查：查看 Google 索引的单个网址版本（判定结果、覆盖范围、上次抓取时间、robots.txt、Google 选定的规范网址与声明的网址、站点地图、富媒体搜索结果）。
list_sitemaps / get_sitemap	已提交的站点地图：类型、上次提交／下载时间、错误、警告和已提交的网址数量。
connect	连接这台计算机：返回供你在浏览器中批准的链接和代码（你的 AI 会显示它们；支持 MCP URL 引导的客户端会提供打开链接的选项）。明确说 “connect my Search Console” 即可启动连接。
connection_status	显示已连接（附设备名称）、等待批准（再次显示链接和代码）、未连接，或连接失败的原因。等待进行中的登录完成，最长 25 秒。

关于 Search Console 数据须知

• **延迟：**数据通常会在 2–3 天后提供。默认日期范围为截至 3 天前的 28 天。data_state: "all" 会加入更新、仍在变化的数据；结果会说明数据从哪一天开始不完整。
• 日期采用太平洋时间（Search Console 的日期分界时间）。相对日期（"yesterday"、"7daysAgo"）也按太平洋时间计算。
• **匿名查询：**过于少见而不予显示的查询（出于隐私考虑），不会出现在按查询分组或筛选的行中，因此按查询统计的行合计会低于按日期、国家或设备统计的总数。出于这个原因，compare_periods 会单独报告资源总数。
• **行数限制：**一次调用最多返回 25,000 行（使用 start_row 分页），Google 每种搜索类型每天最多公开 50,000 行，并按点击次数排序。
• **汇总方式：**按网页分组或筛选时，每个 URL 都会单独计数（byPage），因此总数会与资源级总数不同。
• Discover 和 Google News不支持 aggregation_type: "byProperty"。
• **配额（Google 的配额）：**Search Analytics 每个站点和每位用户每分钟允许 1,200 次查询；此外还有负载配额，耗时较长且同时按查询和网页级别请求的调用会更快耗尽配额。URL Inspection 每天允许 2,000 次检查，每个资源每分钟 600 次，因此 inspect_url 适合检查少量重要 URL，而不是整个站点地图。

find_opportunities 使用粗略的基准点击率曲线（排名 1 ≈ 28%，排名 3 ≈ 10%，排名 10 ≈ 2%）为行排序。这只是用于确定优先级的经验法则，并非 Google 数据或预测。

故障排除

**“尚未连接”（显示链接和类似 ABCD-1234 的代码）：**AI 会显示这些内容。在任意浏览器中打开链接（不必在这台机器上），登录 Tag Pilot，确认代码匹配并批准，然后允许访问 Search Console，接着告诉 AI 你已完成：它会重试你的问题（或调用 connection_status）。服务会在后台持续检查，因此无需重启。代码有效期为 10 分钟；过期后，再次发起请求（或说“连接 Search Console”）即可获取新代码。若要改为从终端连接（例如通过 SSH），请运行 npx -y @tagpilot/search-console-mcp login：它会显示链接、框中的代码和倒计时，并等待你批准。

**“已登录的 Google 账号无权访问 Search Console 资源……”：**使用 list_sites，并将 site_url 设置为列表中显示的准确值（域名资源使用 sc-domain:，URL 前缀需带尾部斜杠）。若要使用其他 Google 账号，请运行 npx -y @tagpilot/search-console-mcp logout，然后重新连接。

**“这台电脑已与 Tag Pilot 断开连接”：设备已被撤销授权；再次发起请求以重新连接。“你的 Google 登录已过期或被撤销”：**再次发起请求并重新批准。

**配额错误：**等待几分钟（Search Analytics）或等到明天（URL Inspection）。

检查设置：npx -y @tagpilot/search-console-mcp status。日志会写入 stderr。

配置

无需配置任何内容。所有变量均为可选项：

变量
TAGPILOT_API_KEY	用于无头/CI 设置的 gsc:mcp 密钥。跳过设备连接。
TAGPILOT_API_URL	Tag Pilot API 基础 URL。默认值为 https://api.tagpilot.io。
SEARCH_CONSOLE_MCP_NO_BROWSER	设置为 1 时，仅打印/返回链接，不打开浏览器。
SEARCH_CONSOLE_MCP_BROWSER	要打开的浏览器（macOS 应用名称，或 Linux/Windows 上的命令）。
SEARCH_CONSOLE_MCP_AUTH_WAIT_SECONDS	工具调用等待连接的时长，超时后返回链接。默认值为 45。
SEARCH_CONSOLE_MCP_CONFIG_DIR	凭据目录。默认值为 ~/.config/tagpilot/search-console-mcp。

命令：npx -y @tagpilot/search-console-mcp [serve|login|logout|status|--help|--version]。

开发

请参阅仓库 README。SEARCH_CONSOLE_MCP_WEBMASTERS_API_URL 和 SEARCH_CONSOLE_MCP_INSPECTION_API_URL 可将 Google 调用指向模拟服务（由 npm run e2e 使用）。

许可证

Apache License 2.0。版权所有 2026 Tag Concierge sp. z o.o.。该许可证不涵盖 Tag Pilot 名称或徽标（请参阅 NOTICE）。