gsc-ga4-mcp

一个小型本地 MCP 服务器，为 Claude Code 提供对 Google Search Console 和 GA4 的只读访问，另加几个用来交叉对比这两个数据集的工具。

问题

在 AI 助手里做 SEO 工作，通常意味着先从 Search Console 导出 CSV，再从 GA4 导出更多 CSV，把两者粘贴到对话中，然后每次想要一个新数字都要重来一遍。这两份数据也永远不会自动对齐：Search Console 只知道展示次数、点击次数和点击率（CTR）；GA4 只知道会话数、互动数和转化数。要回答“哪些页面有流量却在浪费流量”，得人工按 URL 把它们关联起来。

Google 为 Analytics 发布了官方 MCP server，但其中并不包含 Search Console。社区里确实有 Search Console 服务器，但如果数据属于客户，自己维护一个能端到端读懂的轻量封装器，总胜过信任别人的实现。

本服务器直接从你自己的机器上、以只读权限调用 Google 官方 API。

Related MCP server: Google Search Console MCP Server

它能做什么

通过 stdio 提供二十个 MCP 工具。

Search Console

GA4

组合分析

配置

project_mappings 和 project_lookup 会读取一个本地文件，把项目或客户名称映射到其 GSC 属性和 GA4 属性，这样你只需要说“对比 example.com 的 GSC 和 GA4”，而不用记住 properties/123456789。

技术栈

Node.js + TypeScript。服务器使用 @modelcontextprotocol/sdk，认证使用 google-auth-library，工具模式结构使用 zod。没有数据库，没有托管后端，没有遥测 —— 进程在本地运行，并由 Claude Code 通过 stdio 启动。

权限范围只读，且这是唯一的权限面：

• https://www.googleapis.com/auth/webmasters.readonly

• https://www.googleapis.com/auth/analytics.readonly

凭据位于仓库之外，默认路径为 ~/.config/gsc-ga4-mcp/。

设置

1. 安装

git clone https://github.com/YOUR_USER/gsc-ga4-mcp.git
cd gsc-ga4-mcp
npm install
npm run build
mkdir -p ~/.config/gsc-ga4-mcp

2. 启用 API

在 Google Cloud Console 中创建或选择一个项目，然后启用：

• Google Search Console API

• Google Analytics Data API

• Google Analytics Admin API

3. 创建 OAuth 凭据

在 API 与服务 → OAuth 同意屏幕下配置同意屏幕。如果你管理的资源并不都在同一个 Google Workspace 中，请选择“外部”并把自己添加为测试用户，只要应用仍处于测试模式即可。

在 API 与服务 → 凭据下，创建一个类型为 Desktop app 的 OAuth 客户端、下载 JSON，并保存为 ~/.config/gsc-ga4-mcp/oauth-client.json。

如果你为多个客户工作，希望把权限隔离到不同账户，请改用服务账号，并在每个 GSC 与 GA4 属性下为该服务账号邮箱添加只读权限。设置 GOOGLE_AUTH_MODE=service_account，并把 GOOGLE_SERVICE_ACCOUNT_KEY_FILE 指向对应密钥。

4. 配置

cp .env.example .env
cp projects.example.json ~/.config/gsc-ga4-mcp/projects.json

.env 中的路径必须是绝对路径 —— ~ 不会被展开。

GOOGLE_AUTH_MODE=oauth
GOOGLE_OAUTH_CREDENTIALS_FILE=/Users/YOUR_USER/.config/gsc-ga4-mcp/oauth-client.json
GOOGLE_TOKEN_PATH=/Users/YOUR_USER/.config/gsc-ga4-mcp/token.json
GOOGLE_OAUTH_REDIRECT_URI=http://127.0.0.1:3000/oauth2callback
PROJECTS_CONFIG=/Users/YOUR_USER/.config/gsc-ga4-mcp/projects.json
MCP_DEFAULT_GSC_SITE=sc-domain:example.com
MCP_DEFAULT_GA4_PROPERTY=properties/123456789
MAX_ROWS=25000

项目映射（projects.json）：

{
  "projects": [
    {
      "name": "My Site",
      "client": "Internal",
      "domain": "example.com",
      "gscSiteUrl": "sc-domain:example.com",
      "ga4Property": "properties/123456789",
      "notes": "Replace with the real GA4 property ID."
    }
  ]
}

5. 授权

npm run auth

脚本会在 127.0.0.1:3000 上启动一个本地监听器，并打印一个 Google 授权 URL。打开该 URL，批准只读权限范围，令牌就会写入 GOOGLE_TOKEN_PATH 所指向的文件。

6. 注册到 Claude Code

claude mcp add google-seo -- node /ABSOLUTE/PATH/TO/gsc-ga4-mcp/dist/index.js
claude mcp list

或者，在你要使用这些工具的项目中提交一个 .mcp.json（参考 .mcp.example.json）：

{
  "mcpServers": {
    "google-seo": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/gsc-ga4-mcp/dist/index.js"],
      "env": {
        "GOOGLE_AUTH_MODE": "oauth",
        "GOOGLE_OAUTH_CREDENTIALS_FILE": "/Users/YOUR_USER/.config/gsc-ga4-mcp/oauth-client.json",
        "GOOGLE_TOKEN_PATH": "/Users/YOUR_USER/.config/gsc-ga4-mcp/token.json",
        "PROJECTS_CONFIG": "/Users/YOUR_USER/.config/gsc-ga4-mcp/projects.json",
        "MCP_DEFAULT_GSC_SITE": "sc-domain:example.com",
        "MCP_DEFAULT_GA4_PROPERTY": "properties/123456789"
      }
    }
  }
}

如果你宁愿把路径和属性默认值放在仓库之外，就用 CLI 注册方式。

与 Claude Code 一起使用

用自然语言提问，Claude 会根据需要自动选择工具。

Use gsc_list_sites and ga4_list_properties. Give me a table of the GSC sites
and GA4 properties I can reach.

Analyse organic traffic for sc-domain:example.com over the last 90 days using
gsc_top_queries and gsc_top_pages.

Cross GSC and GA4 for example.com over the last 90 days. Find pages with high
impressions and low CTR, and rank the opportunities by likely impact.

Run seo_opportunity_report and group the output into quick wins, pages that
need a rewrite, and pages that miss search intent.

Inspect https://www.example.com/page/ with gsc_url_inspection and tell me
whether Google has it indexed.

运行注意事项

• 不要把 .env、token.json、projects.json 以及任何服务账号密钥提交到版本控制。当前仓库自带的 .gitignore 已覆盖它们。

• 客户数据分析是机密信息。不要把完整输出粘贴到客户未批准的工具中。

• 项目或合作结束时，记得撤销令牌或服务账号。

• MAX_ROWS 会限制响应大小。如果输出过长，可以调低该值。

故障排查

• Claude Code 看不到这些工具。 在终端运行 claude mcp list，然后在 Claude Code 内执行 /mcp。

• OAuth 令牌错误。 重新运行 npm run auth，并确认 GOOGLE_TOKEN_PATH 是绝对路径。

• access_denied。 在应用处于测试模式下，把你的邮箱添加为 OAuth 同意屏幕中的测试用户。

• 某个域名在 GSC 中缺失。 你的凭据需要有权限访问对应的那个属性 —— sc-domain:example.com 和 https://www.example.com/ 是不同的属性。

• 某个 GA4 属性缺失。 该用户或服务账号需要至少对对应的账户或属性具备查看者（Viewer）权限。

• gsc_url_inspection 失败。 inspectionUrl 必须位于 siteUrl 之内，且 URL 前缀属性必须以 / 结尾。

• GA4 指标无效。 请使用官方 GA4 维度和指标名，runReport 会拒绝其他内容。

参考链接

• Claude Code MCP 文档

• Model Context Protocol

• Search Console API

• GA4 数据 API

• Google Analytics 管理 API

• Google OAuth 作用域

许可证

MIT。见 LICENSE。