GA4 SEO MCP

English · Español

ga4-seo-mcp — 为 AI Agent 提供端到端的网站测量

端到端地为网站做好测量准备：GA4 + Search Console + PageSpeed，并支持可选且受保护的写入操作。 一个用于 Google Analytics 4 和 Search Console 的开源 Model Context Protocol 服务。大多数 Google MCP 服务只能读取数据；这个服务还能完成设置：属性、网站数据流、关键事件、自定义维度、Search Console DNS 验证、站点地图和 PageSpeed 基线——默认只读，除非你另行确认。

标签： mcp-server · ga4 · google-analytics · search-console · seo · pagespeed · core-web-vitals · keyword-research · claude-code · cursor

_{实际运行：在公开网站上执行 psi_audit，并使用 bootstrap_site_measurement(apply=False) 规划新网站的设置。演示脚本会隐藏账号 ID。}

---

💡 为什么选择它？

每次上线网站都要做同样的杂事：创建 GA4 属性和网站数据流、标记关键事件、注册自定义维度、将域名添加到 Search Console、发布 DNS TXT 记录、验证、提交站点地图，并记录 PageSpeed 基线。ga4-seo-mcp 将这些工作变成一份由 Agent 展示给你的计划，以及一次确认。

	ga4-seo-mcp	Google 官方 GA4 MCP	search-console-mcp	google-seo-mcp
GA4 报告（Data API）	✅	✅	✅	✅
Search Console	✅	—	✅（+ Bing）	✅
PageSpeed Insights / CrUX	✅	—	✅	✅
创建 GA4 属性 + 网站数据流	✅	—	—	—
创建关键事件 / 自定义维度	✅	—	—	✅
Search Console DNS 验证	✅	—	—	—
一次调用生成网站计划 → 应用（幂等）	✅ bootstrap_site_measurement	—	—	—
默认只读	✅ 写入工具甚至不会注册	仅只读	请参阅其文档	✅ 只读模式
工具集	✅	—	—	✅
语言	Python	Python	TypeScript	TypeScript

_{根据各项目截至 2026-10-19 的 README 整理；“—”表示未找到相关文档。欢迎提出更正。这些项目的覆盖范围更广（Bing、AdSense、WordPress、GEO 审核……）；本项目则更深入地专注于测量设置。}

🤝 需要我们代劳吗？

此服务由 Germani Uicab 构建并维护。如果您不想自己运行，ServerStack Solutions 可以为您做好 GA4 + Search Console 测量配置：提供书面计划、配置媒体资源和关键事件、完成 DNS 验证并设置站点地图，以及建立 PageSpeed 基准，并在交付前进行 QA 检查。

---

额外功能：可选的关键词研究，支持 DataForSEO（精确的长尾关键词搜索量）和 Google Ads Keyword Planner（免费、分档显示的搜索量），默认使用 es-MX，也可覆盖此默认设置。

---

⚡ 快速开始

1. 安装 uv 0.13.4 或更高版本 — 客户端通过 uvx 启动服务，无需安装其他内容。

2. 使用最小权限范围登录。 CLI 会根据您启用的工具集输出准确的 gcloud 命令：

uvx ga4-seo-mcp auth-command --client-id-file=oauth-client.json
# gcloud auth application-default login --client-id-file=oauth-client.json --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/webmasters.readonly

运行输出的命令。Google 会在 gcloud 内置的 OAuth 客户端上屏蔽 Analytics 和 Search Console 权限范围，因此您需要使用自己的客户端（一次性设置，只需几分钟）或服务账号 — 两种方式均在 docs/AUTH.md 中说明。

3. 在连接客户端前检查所有内容（只读，不会进行任何更改）：

uvx ga4-seo-mcp doctor
# [ok] credentials found: Credentials via Application Default Credentials
# [ok] access token refreshed
# [ok] token has the 2 scope(s) these toolsets need
# [ok] admin: <n> account(s) visible on the first page
# [ok] data: responded (<n> metrics in the schema)
# [ok] gsc: <n> site(s) visible
# [ok] psi: no Google login needed; PAGESPEED_API_KEY set
# all checks passed

4. 将其添加到客户端（以下以 Claude Code 为例；其他客户端见下文）：

claude mcp add ga4-seo -- uvx ga4-seo-mcp

提问：“列出我的 GA4 媒体资源，并显示第一个媒体资源上周的会话数。”

---

🧰 工具集、权限范围和工具

使用 --toolsets（或 GA4SEO_TOOLSETS）仅启用所需功能。默认值：admin,data,gsc,psi。仅注册已启用工具集中的工具，并相应设置 OAuth 权限范围。

工具集	内容	权限范围（只读）	使用 --enable-writes 时的额外权限范围	工具（读 + 写）
admin	GA4 Admin API：账号、媒体资源、数据流、关键事件、自定义维度、Ads 关联、bootstrap_site_measurement	analytics.readonly	analytics.edit	9 + 10
data	GA4 Data API：报告、实时数据、热门页面、事件、流量来源、资产组合	analytics.readonly	—	8 + 0
gsc	Search Console：查询、页面、站点地图、添加域名 + DNS 验证	webmasters.readonly	webmasters, siteverification	5 + 3
psi	PageSpeed Insights：Lighthouse 实验室数据 + CrUX 实际用户数据	无（建议设置 PAGESPEED_API_KEY）	—	2 + 0
dataforseo	DataForSEO 关键词建议和精确搜索量（付费）	无（DATAFORSEO_LOGIN / DATAFORSEO_PASSWORD）	—	2 + 0
ads	Google Ads Keyword Planner（需要 pip install 'ga4-seo-mcp[ads]'）	adwords	—	2 + 0

实际注册表中的工具数量：使用默认配置时为 24 个，使用 --enable-writes 时为 37 个，使用 --toolsets data 时为 8 个，启用所有工具集和写入功能时为 41 个。完整列表及说明见 docs/TOOLS.md（根据注册表生成，并在 CI 中检查）。

提示词： audit_ga4_setup、seo_360_audit、portfolio_performance_digest 和 launch_site_measurement（引导式流程：计划 → 您确认 → 应用 → DNS 验证 → 站点地图 → PageSpeed 基准）。

bootstrap_site_measurement

bootstrap_site_measurement(site_url="https://example.com", account_id="123456789",
                           property_display_name="Example", time_zone="America/Mexico_City",
                           currency_code="USD", key_events=["generate_lead"],
                           custom_dimensions=[{"parameter_name": "plan_type", "display_name": "Plan type"}])

• apply=False（默认）：生成计划。 只读且始终注册。它会根据网站域名查找现有资源和 Web 数据流、已声明的关键事件和自定义维度，以及 Search Console 域名资源，并列出将要创建的内容。
• apply=True：执行计划。 仅当服务使用 --enable-writes 运行时才有效；否则会在执行任何操作前失败。此操作具有幂等性：已存在的内容会跳过，因此可以重复运行。返回逐步报告，其中包含衡量 ID（G-…）和 DNS TXT 令牌。
• DNS 验证（sc_verify_site_dns）和站点地图提交（sc_submit_sitemap）仍需显式作为后续步骤执行：你必须先发布 TXT 记录。

---

🔒 安全模型

默认设置适合单用户在笔记本电脑上使用。详情和威胁模型见：SECURITY.md。

• 默认只读。 未启用 --enable-writes（或 GA4SEO_ENABLE_WRITES=1）时，创建、更新、删除、提交或验证相关工具根本不会注册——模型无法调用不存在的工具。
• 每个工具都带有 MCP 注解：读取操作使用 readOnlyHint，删除和更新操作使用 destructiveHint，重复执行无害时使用 idempotentHint，所有工具均使用 openWorldHint。支持这些注解的客户端可以自动批准读取操作，并在写入前询问。
• 最小权限范围：每个 Google 客户端只请求其调用所需的权限范围；auth-command 只请求对应工具集的权限范围。
• HTTP 传输（--transport streamable-http）：绑定到 127.0.0.1，启用 DNS 重绑定防护，除非设置 MCP_CORS_ORIGINS，否则关闭 CORS；还可选用令牌 MCP_AUTH_TOKEN（未提供时返回 401）。未设置令牌却监听 0.0.0.0 时会打印警告；局域网客户端需要设置 MCP_ALLOWED_HOSTS，否则重绑定防护会返回 421。
• 机密信息（DataForSEO、Ads 开发者令牌、PageSpeed 密钥）仅从环境变量或权限为 chmod 600 的文件中读取，绝不会记录到日志或在错误中返回。

---

⚙️ 配置

变量	默认值	说明
GOOGLE_APPLICATION_CREDENTIALS	—	服务账号密钥文件。未设置时使用来自 gcloud 的应用默认凭据。
GA4SEO_TOOLSETS	admin,data,gsc,psi	与 --toolsets 相同。
GA4SEO_ENABLE_WRITES	0	1 = 与 --enable-writes 相同。
PAGESPEED_API_KEY	—	建议设置：匿名 PageSpeed 配额为共享配额，且经常耗尽（429）。
DATAFORSEO_LOGIN、DATAFORSEO_PASSWORD	—	dataforseo 工具集。
GOOGLE_ADS_DEVELOPER_TOKEN	—	ads 工具集，或使用 chmod 600 设置 ~/.config/ga4-seo-mcp/dev-token。
GOOGLE_ADS_LOGIN_CUSTOMER_ID	—	仅在通过管理器（MCC）账号操作时需要。
MCP_TRANSPORT	stdio	stdio、streamable-http 或 sse。
MCP_HOST / MCP_PORT	127.0.0.1 / 8000	HTTP 绑定地址和端口。特定的非环回地址会加入允许的 Host 标头；0.0.0.0 不会，因此局域网客户端需设置 MCP_ALLOWED_HOSTS。
MCP_AUTH_TOKEN	—	要求每个 HTTP 请求都提供 Authorization: Bearer <token>。
MCP_CORS_ORIGINS	—	浏览器客户端使用的、以逗号分隔的精确来源。切勿使用 *。
MCP_ALLOWED_HOSTS	—	客户端使用的、以逗号分隔的主机/IP 值（例如 192.168.1.10）。绑定到 0.0.0.0 并通过局域网连接时必须设置；DNS 重绑定防护会拒绝其他所有连接，并返回 421。

复制 .env.example 作为起始配置。

---

🔌 连接客户端

每个客户端都通过 stdio 启动服务。只有在实际要设置网站的会话中，才将 --enable-writes 添加到 args。

Claude Code

claude mcp add ga4-seo -- uvx ga4-seo-mcp
# with options:
claude mcp add ga4-seo -e PAGESPEED_API_KEY=your-key -- uvx ga4-seo-mcp --toolsets admin,data,gsc,psi

Claude Desktop（claude_desktop_config.json）和 Cursor（~/.cursor/mcp.json）

{
  "mcpServers": {
    "ga4-seo": {
      "command": "uvx",
      "args": ["ga4-seo-mcp"],
      "env": { "PAGESPEED_API_KEY": "your-key" }
    }
  }
}

VS Code（.vscode/mcp.json）

{
  "servers": {
    "ga4-seo": {
      "type": "stdio",
      "command": "uvx",
      "args": ["ga4-seo-mcp"]
    }
  }
}

Docker（stdio）。以只读方式挂载凭据文件——来自 gcloud 的 ADC 文件或服务账号密钥——并以你自己的用户身份运行，以便容器能够读取 0600 文件：

docker run -i --rm --user "$(id -u):$(id -g)" \
  -v ~/.config/gcloud/application_default_credentials.json:/creds/credentials.json:ro \
  -e GOOGLE_APPLICATION_CREDENTIALS=/creds/credentials.json \
  ghcr.io/germaniu/ga4-seo-mcp

HTTP（多个客户端共用一个服务）：

MCP_AUTH_TOKEN=$(openssl rand -hex 32) uvx ga4-seo-mcp --transport streamable-http
# endpoint: http://127.0.0.1:8000/mcp  (send Authorization: Bearer <token>)

---

🩹 故障排查

症状	原因和解决方法
在 gcloud ... login 期间出现 This app is blocked / access_denied	gcloud 内置客户端无法请求 Analytics 或 Search Console 范围。使用你自己的 OAuth 客户端（--client-id-file），并将自己添加为其同意屏幕的测试用户 — docs/AUTH.md。
cloud-platform scope is required but not requested	使用 ga4-seo-mcp auth-command 打印的命令：gcloud 需要在列表中包含 cloud-platform。服务本身绝不会请求此范围。
403 ... API has not been used in project	在你的配额项目中启用 Google Analytics Admin API、Google Analytics Data API 和 Search Console API，然后运行 gcloud auth application-default set-quota-project my-gcp-project。
403 ... does not have sufficient permissions for this property	将你的用户（或服务账号电子邮件地址）添加到 GA4 媒体资源或 Search Console 网站。
ga4-seo-mcp doctor 提示令牌缺少范围	你在启用工具集或写入功能之前就已登录。重新运行 auth-command 的输出命令。
写入工具未显示	使用 --enable-writes 启动服务。此功能默认关闭，这是有意为之。
PageSpeed Insights error 429	匿名配额由所有人共享。创建 API 密钥并设置 PAGESPEED_API_KEY。
Keyword Planner 的搜索量看起来经过了取整（10、30、170、210……）	对于没有活跃支出的账号，Google Ads 会报告分档搜索量。要获取精确数据，请使用 dataforseo 工具集。
已删除的 GA4 媒体资源仍然显示	delete_property 是软删除：Google 会将其保留在回收站中 35 天（list_properties(include_deleted=True)）。
HTTP 返回 421 Invalid Host header	DNS 重绑定保护。请使用绑定的主机连接（127.0.0.1/localhost，或 MCP_HOST 地址）。
HTTP 返回 401	发送 Authorization: Bearer $MCP_AUTH_TOKEN。

---

📚 文档

• docs/AUTH.md — 自有 OAuth 客户端与服务账号、各工具集所需的范围、测试用户。
• docs/TOOLS.md — 所有工具和提示词，均由注册表生成。
• docs/ARCHITECTURE.md — 模块、注册机制和安全层。
• SECURITY.md · CONTRIBUTING.md · CHANGELOG.md

🧪 开发

uv sync --all-extras
uv run ruff check . && uv run ruff format --check . && uv run pytest
uv run python scripts/smoke_stdio.py --expect 24   # real stdio initialize + tools/list

📄 许可证

MIT。与 Google 无关联，也未获得 Google 的认可。Google Analytics、Search Console 和 PageSpeed Insights 是 Google LLC 的商标。