seo-analytics-mcp

Google Search Console、GA4 和 IndexNow —— 作为一个 MCP 服务器。

向 Claude 询问你自己的网站。哪些在排名、哪些有变化、哪些被收录、哪些在转化。

"Which pages lost the most clicks in the last 28 days versus the 28 before?"
"How is /pricing doing?"
"Is https://example.com/new-post indexed yet?"
"Which pages rank on page one but get almost no clicks?"
"Top 20 queries for the blog last month, and which of them convert in GA4."

你授权你自己的 Google 账户，使用你自己的 Google Cloud 项目中的 OAuth 客户端。你的访问不会经过任何其他人，此仓库不包含任何凭据，你消耗的每个 Google 配额都是你自己的。

目录

安装 · 设置 · 七天问题 · 工具 · 响应格式 · 配置 · 写入操作 · 配置文件 · 设计 · 故障排除 · 开发

Related MCP server: GSC Analyst Connector

安装

需要 Python 3.10+ 和 uv。

uvx seo-analytics-mcp doctor      # no install needed — prints your setup steps, in order

doctor 是整个上手体验的核心。它会准确告诉你每个阶段缺少什么、接下来该运行什么。如果你在这里什么都不读，那就运行它。

设置

在 Google Cloud 控制台点击六次，然后运行一条命令。一次完成，十分钟。

创建一个 Google Cloud 项目 —— 或复用现有项目。 console.cloud.google.com/projectcreate

启用 API。 Search Console 是必需的；GA4 两个 API 是可选的。

searchconsole · analyticsdata · analyticsadmin

配置同意屏幕，然后点击发布应用。 console.cloud.google.com/auth/overview

选择外部并发布。你是自己应用的唯一用户，因此 Google 的个人使用例外适用，无需验证。Workspace 用户可以选择内部。

不要跳过发布步骤 —— 参见下文。

创建一个类型为 Desktop app 的 OAuth 客户端并下载 JSON。 console.cloud.google.com/auth/clients

Web 应用客户端无法执行此服务器所需的回环重定向。doctor 会检查这个特定错误，因为这是最容易犯的错误。

在终端中授权一次：

uvx seo-analytics-mcp auth --client-secret ~/Downloads/client_secret_*.json

你的浏览器会打开。Google 会显示 "Google 尚未验证此应用" —— 对于你自己的客户端这是预期的：高级 → 继续。令牌会以 0600 权限模式保存在你的配置文件目录中。

检查，然后连接：

uvx seo-analytics-mcp doctor      # eleven checks; exit 0 means it will work

连接它

claude mcp add seo \
  -e GSC_DEFAULT_SITE=sc-domain:example.com \
  -e GA4_DEFAULT_PROPERTY=properties/123456789 \
  -- uvx seo-analytics-mcp

{
  "mcpServers": {
    "seo": {
      "command": "uvx",
      "args": ["seo-analytics-mcp"],
      "env": {
        "GSC_DEFAULT_SITE": "sc-domain:example.com",
        "GA4_DEFAULT_PROPERTY": "properties/123456789"
      }
    }
  }
}

然后完全退出 Claude Desktop（⌘Q —— 仅关闭窗口不够）并重新打开。

[!NOTE] 该配置中没有凭据路径。令牌位于 seo-mcp auth 写入的配置文件目录中，因此整个块可以安全地粘贴到 GitHub issue 中。

七天问题

[!WARNING] 如果服务器正常工作，然后大约一周后停止，原因就在这里。

对于任何发布状态仍为 Testing 的外部 OAuth 应用，Google 签发的刷新令牌在七天后过期。明显的设置路径 —— 创建项目、创建客户端、将自己添加为测试用户 —— 会让你停留在此状态。

修复方法只需一次点击：在同意屏幕上，将受众设置为外部，然后点击发布应用。然后运行 uvx seo-analytics-mcp auth --reauth。

doctor 会标记出仍然可能是 Testing 令牌的年轻令牌，并且服务器返回的每个 invalid_grant 错误都会完整解释这一点。这不是服务器的问题 —— 但这将是针对它提交的最常见问题。

工具

十三个工具：十个映射到上游操作，两个连接数据源，一个纯粹是为了让模型能告诉困惑的用户该做什么。

响应格式

每个读取工具都返回相同的四个键。有界、自描述，并携带自身的注意事项。

{
  "summary": {
    "source": "gsc",
    "rows_returned": 10,        // what you see
    "rows_matched": 1847,       // what exists upstream
    "date_range": "2026-07-29..2026-08-25",   // resolved, always echoed
    "data_state": "final",
    "totals": { "clicks": 4730, "impressions": 512903, "ctr": 0.0092, "position": 12.4 }
  },
  "rows": [ /* capped at min(row_limit, 1000) */ ],
  "notes": [
    "Google anonymises rare queries: these rows do NOT sum to property totals.",
    "dataState=final excludes the most recent 2-3 days.",
    "1837 further rows were not included inline."
  ],
  "export": "~/.../exports/a1b2c3.csv"        // only when rows spilled
}

三个约定在所有地方都成立：

总计覆盖所有获取的行，而不仅仅是显示的行 —— 一个看到十行和十行总计的模型无法区分截断和现实。比率从不取平均值：ctr 根据点击 ÷ 展示重新计算，position 按展示加权，engagementRate 是互动 ÷ 会话。

注意事项随数据一起传递。 无论哪一层知道注意事项，都会附加它：客户端知道请求了 query 维度，shape() 知道它丢弃了多少行，GA4 知道响应被采样。当模型正在查看数字时，文档字符串单独就会丢失这些信息。

错误会指出修复方法。 403 会告诉你检查哪个授权以及在哪里 —— 绝不会是原始的 Google 错误正文。

The authorised Google account has no access to sc-domain:example.com. Confirm the
account you authorised is the one with access — Search Console grants are per-property
under Settings > Users and permissions, GA4 grants are per-property under Admin >
Property access management. If access was added recently, run `seo-mcp auth --reauth`.

配置

每个变量都是可选的。优先级：工具参数 → 环境变量 → 配置文件 config.json。

日期

每个日期参数都接受 YYYY-MM-DD、today、yesterday 或 NdaysAgo。响应会回显它们实际使用的绝对范围，因为如果模型猜错了今天的日期，会产生一个空结果，读起来就像 "流量降到了零"。

Search Console 有 2–3 天的延迟，并保留约 16 个月的数据；超出这些范围的范围会被标记或拒绝，而不是静默返回空结果。GA4 以属性自身的时区报告，因此其日期与 Search Console 的日期不完全对齐 —— 响应会在重要之处说明这一点。

写入操作

两个工具会对你机器之外的世界产生影响。两者都故意设计得比较麻烦。

[!IMPORTANT] 单独的 confirm 标志不是安全机制 —— 它是模型填写的参数，而同样的误读导致错误的 URL 时，也会在旁边产生 confirm=true。

没有干运行就无法伪造令牌，而且更改一个 URL 就会导致不匹配。两个工具还带有 destructiveHint 注解，因此如果客户端将破坏性工具置于自己的批准提示之后，它会这样做。

默认是只读范围。一个陌生人安装一个 SEO 工具，立即要求修改其 Search Console 属性的权限，会合理地拒绝。

配置文件

一台机器上有多个 Google 账户 —— 适用于同时持有客户属性的代理机构。

uvx seo-analytics-mcp auth --profile client-a --client-secret ./client-a.json
uvx seo-analytics-mcp auth --profile client-b --client-secret ./client-b.json
uvx seo-analytics-mcp profiles list

为每个 MCP 服务器条目设置 SEO_MCP_PROFILE。缓存键包含配置文件，因此两个账户永远不会互相提供数据。

一个配置文件就是一个目录 —— 你首先会要求用户删除的东西：

uvx seo-analytics-mcp profiles rm client-a --yes

它们位于 ~/Library/Application Support/seo-mcp/（macOS）、$XDG_CONFIG_HOME/seo-mcp/（Linux）或 %APPDATA%\seo-mcp\（Windows）。

设计

四层，严格向下。如果搞错了，认证流程就会进入工具调用内部，而这正是整个设计要防止的失败。

flowchart TD
    subgraph L4["Entry points"]
        S[server.py<br/><i>MCPServer, stdio</i>]
        C[cli.py<br/><i>auth · doctor · profiles · serve</i>]
    end
    subgraph L3["Tools — argument surface, docstrings, cache policy"]
        T[13 handlers<br/><i>no HTTP, no credentials, no row shaping</i>]
    end
    subgraph L2["Clients — the only modules that speak HTTP"]
        G[gsc.py]
        A[ga4.py]
        I[indexnow.py]
    end
    subgraph L1["Leaves — importable by anyone, import nobody"]
        LV[shaping · errors · config · cache · auth/store · auth/scopes]
    end
    F[auth/flow.py<br/><i>loopback + PKCE · opens a browser</i>]

    S --> T
    C --> T
    C -.->|only reachable from here| F
    T --> G & A & I
    G & A & I --> LV

浏览器流程绝不能运行在工具调用内部。 一个在 stdio 上阻塞等待人类完成同意屏幕的 MCP 工具看起来像挂起的服务器，而模型无法提供帮助。一条 CLI 命令，运行一次，就是全部区别 —— 并且一个测试会遍历每个模块的 AST 来强制执行这一点。

测试还机械地执行其他规则：shaping.py 不导入任何 Google 库（这就是为什么行逻辑可以在没有凭据的情况下完全单元测试），工具不导入任何 HTTP 库，服务器路径上的任何东西都不调用 print() —— 在 stdio 传输上，stdout 承载 JSON-RPC，一个多余的 print 就会破坏流。

故障排除

每份问题报告都应包含 seo-mcp doctor --json。 它不包含任何凭据 — 只有路径、版本、哪些检查通过以及哪些 API 有响应。

开发

uv sync --extra dev
uv run pytest -q                    # 147 tests · no credentials · no network
uv run python scripts/smoke.py      # drives the server over real stdio JSON-RPC
uv run ruff check src tests

python3 -m venv .venv && ./.venv/bin/pip install -e ".[dev]"
./.venv/bin/python -m pytest -q
./.venv/bin/python scripts/smoke.py ./.venv/bin/seo-mcp

scripts/smoke.py 以子进程方式启动服务器，完成 MCP 握手，列出工具并调用其中几个 — 使用一次性配置文件目录，因此您的真实令牌不会受到影响。这是在创建任何 Google 凭据之前确认协议端正常工作的最快方式。

若要手动调试，MCP Inspector 只需要 Node 即可：

npx @modelcontextprotocol/inspector ./.venv/bin/seo-mcp            # web UI
npx @modelcontextprotocol/inspector --cli ./.venv/bin/seo-mcp \
    --method tools/call --tool-name auth_status                    # scriptable

自动化测试未覆盖的内容： OAuth 流程本身和真实的 IndexNow 提交。两者都需要人工操作和真实域名，而模拟它们只会测试模拟本身。它们属于一份简短的手动发布检查清单。

它不会做的两件事

[!NOTE] IndexNow 不会触达 Google。 参与者包括 Bing、Yandex、Naver、Seznam.cz、Yep 和 Amazon — 一个端点会向所有这些平台传播。Google 不参与其中，而且 Google 自己的 Indexing API 只接受带有 JobPosting 或 BroadcastEvent 结构化数据的页面。如果您安装此工具是期望 Google 索引更快，那您会失望的。

[!NOTE] 查询行永远不会合计为总数。 Google 会对罕见查询进行匿名化处理，因此任何按 query 维度进行的细分都会少计。每个包含该维度的响应都会重复这一警告，因为如果没有这一警告，模型拿到这些行后会自信地计算出错误的百分比。

贡献

欢迎提交 Issue 和 Pull Request。无凭据测试套件会在每次推送时在 Linux、macOS 和 Windows 上的 Python 3.10 和 3.13 中运行 — 如果本地通过，CI 中也会通过。

重命名工具或更改参数会破坏用户保存的所有提示词。这些更改会记录在 CHANGELOG.md 中，并且在 1.0 之前是次要版本升级，之后是主要版本升级。

许可证

MIT。