Google Webtools MCP

google-webtools-mcp

一个 MCP 服务，可让 AI Agent 直接访问 Google Search Console 和 Google Analytics 4，管理资源、分析搜索表现、检查索引状态、生成 GA4 报告并验证网站。

---

面向 AI Agent

如果 Agent 正在驱动此服务，请先让它查看 SKILL.md （俄语）。该文件介绍了操作顺序——发现资源、验证、站点地图、索引检查、 常规审计流程——如何解读 URL 检查结果、Search Console 不会提供哪些数据、哪些调用会消耗配额，以及哪些工具会写入线上配置。

---

功能

此服务基于五个 Google API，提供 39 个工具：

API	用途
Search Console API（webmasters v3）	资源、站点地图、搜索分析
Search Console API（searchconsole v1）	URL 检查
Google Analytics Admin API（v1beta）	GA4 账号、资源、数据流
Google Analytics Data API（v1beta）	GA4 报告、实时数据、元数据
Site Verification API（v1）	验证令牌、所有权验证

除原始 API 访问外，工具响应还会经过本地分析层处理： 基于排名位置的 CTR 基准、趋势检测、查询意图分类、 机会评分和建议引擎。大多数工具返回易读的 Summary 和 Data 区块，而非纯 JSON；如果有值得说明的内容，还会提供 Recommendations 和 Limitations 部分。

基础设施：内存中的 TTL+LRU 缓存（搜索分析数据的日期范围结束于最近 2 天内时缓存 15 分钟，超过 2 天时缓存 1 小时；站点地图缓存 15 分钟；站点列表缓存 30 分钟；URL 检查缓存 1 小时）、限速器（20 次请求/秒，突发上限为 30 次），以及两种传输方式——stdio（默认）和无状态 Streamable HTTP。

---

工具

Search Console 资源（4 个）

工具	适用场景
list_properties	起点——查看你可以访问的所有 GSC 资源，以及你在每个资源上的权限级别。
get_property_details	查看特定资源的类型和权限级别。
add_property	在 Search Console 中注册新网站（验证需单独进行）。
delete_property	从已认证账号的 Search Console 网站列表中移除资源。不会销毁历史数据——之后可以重新添加该资源。

站点地图（4 个）

工具	适用场景
list_sitemaps	查看已提交的站点地图，以及 Google 是否报告错误或警告。
get_sitemap_details	深入查看某个站点地图：按内容类型统计 URL 数量、上次下载时间、错误和警告数量。
submit_sitemap	发布或迁移站点地图后提交新站点地图。
delete_sitemap	撤回已过时、重复或返回错误的站点地图。

搜索表现（6 个）

工具	适用场景
get_search_analytics	原始查询——可全面控制维度、筛选条件、搜索类型、行数限制、数据状态和聚合方式。适用于下方经过整理的工具无法满足需求的情况。
get_performance_summary	“我们的表现如何？”——点击次数、展示次数、CTR、排名，并与上一时段进行比较。如果上一时段完全没有数据，则不提供趋势建议。
compare_periods	并排比较两个指定日期范围（例如发布前后比较、季节性比较）。
get_top_queries	按点击次数列出热门查询，并根据其排名位置的 CTR 基准进行评分。
get_top_pages	按点击次数列出热门网页，并进行相同的 CTR 分析。
get_traffic_by_device	按桌面设备、移动设备和平板设备细分流量，以发现特定设备的问题。

机会（5）

工具	使用时机
find_quick_wins	“哪里还有钱没赚到？”——找出排名靠前但点击不足的查询/页面组合，以及排名刚好在第 1 页之外的组合。每组只会归入一个类别（CTR 1-3、快速提升 >3 到 10、第 2 页 >10 到 20），因此你所选时间段内的数量和点击量估算可以相加。
find_declining_content	在流量损失仍可挽回时及时发现——对比当前时段与上一时段，并分别列出流量下滑的页面和查询排名。
find_ctr_opportunities	找出 CTR 远低于其排名对应基准的页面，并提供逐页修复建议。
find_content_gaps	找出落在错误页面上的查询、曝光量高但点击量为零的查询，以及需要单独创建页面的主题。
find_what_to_build_next	规划内容——按用户意图（问题、比较、问题解决、购买）将查询归入主题集群。

索引（3）

工具	使用时机
inspect_url	为什么这个 URL 没有显示？查看索引状态、移动设备易用性、富媒体搜索结果，以及 FAIL 判定背后的逐项验证问题。
batch_inspect_urls	对一组 URL 执行相同检查（每次最多 50 个）。
check_indexing_issues	审核流量最高的页面，检查索引失败、规范链接不匹配、缺失规范链接和移动设备问题。API 报错的 URL 会标记为未检查；审核的其余部分仍会继续执行。

查询分析（3）

工具	使用时机
analyze_query_landscape	了解需求概况——意图构成、品牌与非品牌查询比例、排名分布。
find_new_queries	对比当前时段与上一时段，找出真正的新查询和快速增长的查询。
find_cannibalization	检测多个自有页面是否在竞争同一查询。排名胜出的页面是点击量最多的页面，而不是平均排名最靠前的页面；对于只有一个页面带来实际流量的查询，不会提供内容整合建议。

报告（2）

工具	使用时机
weekly_seo_report	一键生成每周摘要：趋势、增长项、下滑项、快速提升机会、站点地图健康状况和优先行动。
seo_health_check	给出总体 A–F 评级，并提供流量趋势、CTR 效率、排名分布和站点地图健康状况的子评分。

GA4 管理（7）

工具	使用时机
ga4_list_accounts	查看凭据可访问的所有 GA4 账号和媒体资源。
ga4_list_properties	列出某个账号下的媒体资源。
ga4_get_property	检查媒体资源的配置。
ga4_create_property	创建新的 GA4 媒体资源。写入操作。
ga4_create_data_stream	创建 Web 数据流并获取其衡量 ID（用于安装代码）。写入操作。
ga4_list_data_streams	列出某个媒体资源的数据流。
ga4_get_data_stream	获取单个数据流的详细信息，包括其衡量 ID。

GA4 报告（3）

工具	使用时机
ga4_run_report	运行任意 GA4 报告——选择指标、维度和日期范围（绝对日期或 28daysAgo 之类的相对日期）。
ga4_run_realtime_report	查看当前有哪些用户正在访问网站。
ga4_get_metadata	查找媒体资源支持的维度和指标（包括自定义项）——猜测指标名称前先运行此工具。

网站验证（2）

工具	使用时机
gsc_get_verification_token	获取要放置的令牌及对应验证方式的说明。验证方式：FILE、DNS_TXT、META、ANALYTICS。
gsc_verify_site	放置令牌后完成验证。

---

设置

1. 获取 Google 凭据

在 Google Cloud 项目中启用以下 API：Search Console API、 Google Analytics Admin API、Google Analytics Data API 和 Site Verification API。

服务会请求以下 OAuth 作用域：

https://www.googleapis.com/auth/webmasters
https://www.googleapis.com/auth/analytics.readonly
https://www.googleapis.com/auth/analytics.edit
https://www.googleapis.com/auth/siteverification.verify_only

选项 A — Service account（最适合服务和自动化场景）：

1. 打开 Google Cloud Console → IAM & Admin → Service Accounts → 创建一个账号。
2. 添加密钥 → 创建新密钥 → JSON → 下载。
3. 在 Search Console → Settings → Users and permissions → 添加该服务账号的电子邮件地址。
4. 在 GA4 → Admin → Property access management → 添加同一电子邮件地址。

选项 B — OAuth 2.0（最适合个人本地使用）：

1. 打开 Google Cloud Console → APIs & Services → Credentials → Create credentials → OAuth client ID → Desktop app。
2. 下载客户端密钥 JSON。
3. 首次运行时，服务会在 stderr 中打印授权 URL，并启动临时的本地回调监听器。打开该 URL，授予权限即可。
4. 令牌会存储在 ~/.google-webtools-mcp/token.json，并自动刷新，因此只需授权一次。

2. 环境变量

变量	用途
GOOGLE_APPLICATION_CREDENTIALS	服务账号 JSON 密钥文件的路径。
GOOGLE_SERVICE_ACCOUNT_KEY	内联 JSON 字符串形式的服务账号密钥，适用于挂载文件不方便的 Docker 和 CI 场景。
GSC_OAUTH_CLIENT_SECRETS_FILE	OAuth 客户端密钥 JSON 文件的路径。
PORT	HTTP 传输端口。默认值为 3000。仅在使用 --http 时读取。

身份验证方式按以下顺序尝试，并使用第一个能提供有效凭据的方式。失败的方式会被记录，然后尝试下一种：如果 GOOGLE_APPLICATION_CREDENTIALS 指向不存在或格式错误的文件，服务不会就此停止；如果已配置 OAuth（且已保存令牌），则会改用 OAuth 账号启动。查看 stderr 中的 [auth] Authenticated via … 行，确认实际使用的身份。

1. Service account — GOOGLE_APPLICATION_CREDENTIALS，然后是 GOOGLE_SERVICE_ACCOUNT_KEY，再然后是 ./credentials.json（如果其 type 为 service_account）。
2. Application Default Credentials（gcloud auth application-default login）— 如果已设置 GOOGLE_APPLICATION_CREDENTIALS，则跳过。
3. 通过 GSC_OAUTH_CLIENT_SECRETS_FILE 使用 OAuth。
4. 工作目录中的 ./credentials.json（如果看起来像 OAuth 客户端密钥文件，即包含 installed 或 web 键）。

如果以上方式都失败，服务会在 stderr 中打印设置指南并继续启动，这样主机或目录仍可列出其工具，无需密钥。每次调用工具时都会重新查找凭据；在某种方式成功之前，服务会返回同一条包含设置提示的错误，而不会调用 Google。修复密钥文件后无需重启。

3. 安装

docker run -i --rm \
  -v /absolute/path/to/service-account.json:/creds/sa.json:ro \
  -e GOOGLE_APPLICATION_CREDENTIALS=/creds/sa.json \
  ghcr.io/stufently/google-webtools-mcp:1.2.2

将 /absolute/path/to/service-account.json 替换为第 1 步中的密钥文件路径（Docker 需要绝对路径），然后粘贴该命令。首次运行时，Docker 会拉取镜像（支持 amd64 和 arm64），无需安装其他内容。服务应在 stderr 中打印 Server running on stdio，然后等待客户端连接（按 Ctrl+C 退出）。下方每个客户端配置块都会运行相同的 docker run；密钥文件以只读方式挂载，绝不会写入客户端配置。

该镜像支持服务账号。容器首次运行时 OAuth 无法使用（参见 Docker）；如需使用 OAuth，请从源码构建。

---

已验证的客户端和平台

这里只列出了实际运行过的项目。连接方式 中的其他内容都是文档化的配置，尚未有人端到端验证。

客户端 / 运行时	操作系统	运行方式	状态	证据
Claude Code 2.1	Ubuntu 26.04 LTS, x86_64	从此仓库构建 Docker 镜像，通过 stdio 运行，只读挂载 gcloud ADC	已验证	维护者主机上的日常使用
Codex CLI 0.162	Ubuntu 26.04 LTS, x86_64	同一个 Docker 镜像，通过 stdio 运行	已配置，未单独检查	维护者主机上的配置
Node.js 22, 24, 26	Ubuntu (ubuntu-latest)	npm ci、lint、单元测试、构建	已在 CI 中验证	ci.yml 矩阵
Docker 镜像	Ubuntu (ubuntu-latest)	通过 stdio 运行 initialize + tools/list	已在 CI 中验证	ci.yml，作业 image
Claude Desktop (.mcpb)	macOS, Windows	桌面扩展	未验证	在 CI 中构建了安装包，但从未在实际的 Desktop 中安装
Cursor, Windsurf, Zed	任意	以下配置	未验证	仅有文档说明
macOS, Windows	—	任意客户端	未验证	这些系统上没有 CI 运行器

连接方式

以下每个代码块都会使用 docker 和上方安装命令中的参数启动服务。只需更改 /absolute/path/to/service-account.json。

Claude Code

项目根目录下的项目文件 .mcp.json：

{
  "mcpServers": {
    "google-webtools": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/absolute/path/to/service-account.json:/creds/sa.json:ro",
        "-e",
        "GOOGLE_APPLICATION_CREDENTIALS=/creds/sa.json",
        "ghcr.io/stufently/google-webtools-mcp:1.2.2"
      ]
    }
  }
}

也可以从终端注册同一个服务：

claude mcp add google-webtools -- docker run -i --rm \
  -v /absolute/path/to/service-account.json:/creds/sa.json:ro \
  -e GOOGLE_APPLICATION_CREDENTIALS=/creds/sa.json \
  ghcr.io/stufently/google-webtools-mcp:1.2.2

添加 --scope user，即可在每个项目中使用。

Claude Desktop

claude_desktop_config.json — macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上为 %APPDATA%\Claude\claude_desktop_config.json，Linux 上为 ~/.config/Claude/claude_desktop_config.json。保存后重启 Claude Desktop。

{
  "mcpServers": {
    "google-webtools": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/absolute/path/to/service-account.json:/creds/sa.json:ro",
        "-e",
        "GOOGLE_APPLICATION_CREDENTIALS=/creds/sa.json",
        "ghcr.io/stufently/google-webtools-mcp:1.2.2"
      ]
    }
  }
}

Claude Desktop 也支持一键安装此服务。从 https://github.com/stufently/google-webtools-mcp/releases/latest 下载 .mcpb 并打开。Desktop 会要求提供服务账号 JSON 密钥，该账号必须已添加到 Search Console 和 GA4。

同一版本还包含 checksums.txt，其中列出了每个 .mcpb 的 SHA256。将此文件下载到安装包所在目录并进行校验：

sha256sum -c --ignore-missing checksums.txt   # run next to the downloaded .mcpb

在 macOS 上，shasum -a 256 -c --ignore-missing checksums.txt 可以执行相同的校验。

从下一个标签版本开始，每个 .mcpb 还会附带 GitHub 构建来源证明，并由发布工作流签名。检查安装包是否由此仓库的工作流构建且之后未被替换（需要 GitHub CLI）：

gh attestation verify <bundle>.mcpb --repo stufently/google-webtools-mcp

Cursor

安装后，将 ~/.cursor/mcp.json 中的 /absolute/path/to/service-account.json 替换为密钥文件的路径。也可以手动添加以下代码块。

~/.cursor/mcp.json，或项目中的 .cursor/mcp.json：

{
  "mcpServers": {
    "google-webtools": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/absolute/path/to/service-account.json:/creds/sa.json:ro",
        "-e",
        "GOOGLE_APPLICATION_CREDENTIALS=/creds/sa.json",
        "ghcr.io/stufently/google-webtools-mcp:1.2.2"
      ]
    }
  }
}

Windsurf

mcp_config.json。在 macOS 和 Linux 上，该文件位于 ~/.config/devin/mcp_config.json（或 $XDG_CONFIG_HOME/devin/mcp_config.json）。在 Windows 上，位于 %APPDATA%\devin\mcp_config.json。较旧版本使用 ~/.codeium/windsurf/mcp_config.json。

{
  "mcpServers": {
    "google-webtools": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/absolute/path/to/service-account.json:/creds/sa.json:ro",
        "-e",
        "GOOGLE_APPLICATION_CREDENTIALS=/creds/sa.json",
        "ghcr.io/stufently/google-webtools-mcp:1.2.2"
      ]
    }
  }
}

Zed

Zed 将 MCP 服务称为上下文服务。文件为 settings.json（zed: open settings）：

{
  "context_servers": {
    "google-webtools": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/absolute/path/to/service-account.json:/creds/sa.json:ro",
        "-e",
        "GOOGLE_APPLICATION_CREDENTIALS=/creds/sa.json",
        "ghcr.io/stufently/google-webtools-mcp:1.2.2"
      ],
      "env": {}
    }
  }
}

Codex

codex mcp add google-webtools -- docker run -i --rm \
  -v /absolute/path/to/service-account.json:/creds/sa.json:ro \
  -e GOOGLE_APPLICATION_CREDENTIALS=/creds/sa.json \
  ghcr.io/stufently/google-webtools-mcp:1.2.2

也可以在 ~/.codex/config.toml 中手动配置：

[mcp_servers.google-webtools]
command = "docker"
args = [
  "run", "-i", "--rm",
  "-v", "/absolute/path/to/service-account.json:/creds/sa.json:ro",
  "-e", "GOOGLE_APPLICATION_CREDENTIALS=/creds/sa.json",
  "ghcr.io/stufently/google-webtools-mcp:1.2.2",
]

将密钥作为字符串传递，而不是使用文件

如果挂载文件不方便（例如在 CI 或远程运行器中），请将完整的密钥 JSON 传入 GOOGLE_SERVICE_ACCOUNT_KEY，并让 Docker 从环境变量中转发它： 将 -v … 和 -e GOOGLE_APPLICATION_CREDENTIALS=… 参数替换为 -e GOOGLE_SERVICE_ACCOUNT_KEY，然后在 shell 中设置变量 （export GOOGLE_SERVICE_ACCOUNT_KEY="$(cat service-account.json)"），或在 客户端的 env 块中设置。在 JSON 或 TOML 配置中，密钥必须是单个经过转义的字符串，不能直接粘贴 JSON：运行 jq -c . service-account.json | jq -R . 即可打印出可直接粘贴的内容。这也是 MCP 注册表 条目 io.github.stufently/google-webtools-mcp 要求的格式。

从源代码构建

OAuth 所需，或用于在不使用 Docker 的情况下运行。需要 Node.js 22 或更高版本。

git clone https://github.com/stufently/google-webtools-mcp.git
cd google-webtools-mcp
npm install
npm run build

然后将 node 用作命令，并将 /path/to/google-webtools-mcp/dist/cli.js 作为唯一参数，同时在 env 中提供凭据，例如：

claude mcp add google-webtools \
  --env GSC_OAUTH_CLIENT_SECRETS_FILE=/path/to/client-secrets.json \
  -- node /path/to/google-webtools-mcp/dist/cli.js

HTTP 传输

适用于通过网络与服务通信，而不是启动服务的客户端。此模式为无状态：每个 POST /mcp 请求都会由一个全新的 MCP 服务实例处理，不会发放 Mcp-Session-Id，且请求可以并行运行。Google 凭据、缓存和速率限制器会在请求之间共享。

node dist/cli.js --http           # listens on :3000
PORT=8080 node dist/cli.js --http # or pick a port

端点：

• POST /mcp — MCP JSON-RPC（Streamable HTTP）。发送 Accept: application/json, text/event-stream。
• GET /health — 存活状态检查，返回 {"status":"ok","auth":"<method>"}。
• GET/DELETE /mcp 返回 405：没有从服务端到客户端的数据流，也没有需要终止的会话。

HTTP 端点没有身份验证，并且会监听所有网络接口；与此同时，这些工具会使用你的 Google 凭据（包括写入工具）。请仅在 localhost 上运行，或将其置于具有身份验证功能的代理之后。

Docker

OAuth 授权回调会在容器内的 127.0.0.1 上监听一个随机端口，因此主机上的浏览器无法访问该端口，首次在 Docker 中运行 OAuth 会超时。你可以使用服务账号（参见上方安装命令），或在 Docker 外完成一次授权，然后将 ~/.google-webtools-mcp/token.json 复制到令牌卷中。

docker compose up --build

随附的 docker-compose.yml 以只读方式挂载 ./credentials，并将 OAuth 令牌保存在命名卷中，使其在容器重建后仍然保留。Dockerfile 会自行编译 TypeScript，因此无需本地 dist/；这与发布到 GHCR 的构建相同。

---

示例提示词

• 上周我的网站为什么失去了点击量？
• 哪些页面的排名接近第一页，但几乎没有点击量？
• 这些 URL 已编入索引了吗？未编入索引的页面有什么问题？
• 根据我们已经获得展示的查询，我们接下来应该发布什么内容？
• 搜索流量在手机和桌面设备之间是如何分布的？

更多提示词

• 为 example.com 创建一个 GA4 媒体资源和一个网站数据流，并告诉我用于安装的衡量 ID。
• 哪些页面在争夺同一个查询？

---

限制

• Search Console 数据延迟。 搜索分析数据通常会延迟 2–3 天，且延迟时间会有波动。因此，每个命名周期（last7d、last28d……）都以 API 报告为完整数据的最后一天为基准——该日期取自按日期分组的 dataState: "all" 查询所返回的 first_incomplete_date——而不是以昨天为基准。这样会有意排除最新几天，避免因尾部数据尚未完整收集而扭曲周期对比。需要查看最新数据时，get_search_analytics 仍可接受显式的 dataState 和日期。
• 历史数据最长 16 个月。 这是 Search Console API 的限制，不是服务端限制。
• 行数抽样和上限。 每次请求的搜索分析数据上限为 25,000 行；GA4 报告上限为 100,000 行。Google 可能会对较大范围的 GA4 日期数据进行抽样。
• batch_inspect_urls 每次调用处理 50 个 URL，且 URL Inspection API 对每个资源都有自己的每日配额。
• 网站验证无法一键完成。 服务端会提供令牌和说明；在调用 gsc_verify_site 前，你仍需自行放置文件、DNS 记录或元标记。
• 网域资源无法使用 FILE 或 META 验证——请使用 DNS_TXT。
• 不支持 Google Ads、PageSpeed Insights、CrUX 或 Indexing API。 此服务仅涵盖 Search Console、GA4 和 Site Verification。
• 缓存位于内存中，且按进程隔离。 服务重启时缓存会重置，实例之间不会共享缓存。
• 写入操作会实际生效。 add_property、delete_property、submit_sitemap、delete_sitemap、ga4_create_property、ga4_create_data_stream 和 gsc_verify_site 都会更改实时配置，且没有试运行模式。Search Console 相关操作可通过重新添加资源或重新提交站点地图来撤销；而此服务无法移除已创建的 GA4 资源或数据流。

---

开发

npm install
npm run build      # bundle with tsup
npm run dev        # rebuild on change
npm test           # vitest
npm run lint       # tsc --noEmit

需要 Node.js 22 或更高版本。

发布

版本号位于 package.json 中。server.json（MCP 注册表条目）以及本 README 中所有 ghcr.io/stufently/google-webtools-mcp:<tag> 都由它生成，切勿手动编辑：

npm version patch --no-git-tag-version   # or minor / major
# Docker instead of a local Node:
# docker run --rm -u "$(id -u):$(id -g)" -v "$PWD":/app -w /app node:24-slim \
#   npm version patch --no-git-tag-version

npm version 会更新 package.json 和锁文件，随后运行其 version 生命周期脚本（scripts/sync-version.mjs），重写 server.json 和此处的镜像标签（普通的 npm version patch 也会将这些文件加入暂存区，因此它自己的提交和标签都会完整包含这些更改——但请在 CI 通过后再打标签，如下所示）。添加 CHANGELOG.md 章节，提交并推送到 main，然后等待 CI 完成——其 Versions agree 步骤（npm run check:version）会在这三处版本不一致时失败。之后打标签并推送该标签：

git tag v1.2.3 && git push origin v1.2.3

Publish 工作流会构建并推送镜像（:<version> 和 :latest），并将 server.json 发布到 MCP 注册表；如果标签与 package.json 中的版本不一致，则会拒绝发布。MCPB 工作流会在同一标签上使用 scripts/build-mcpb.sh 构建桌面扩展，写入 dist-mcpb/checksums.txt，为每个捆绑包生成构建来源证明，并将 .mcpb 捆绑包和校验和文件上传到 GitHub Release。它不会推送镜像或注册表条目。

---

致谢

此项目最初是 Magdoub 的 awesome-gsc-mcp 的分支。该项目提供了 Search Console 工具、分析层（CTR 基准、趋势检测、查询分类、机会评分、建议）、缓存和速率限制器。GA4 Admin/Data 和 Site Verification 工具、身份验证改造以及后续修复均在此项目中添加。原项目以 MIT 许可证发布。

---

许可证

MIT — 请参阅 LICENSE。原项目的版权声明也与本项目的版权声明一并保留。