ga-gsc-analytics

只读 MCP 服务器，向 Claude Code / Codex 暴露 Google Analytics 4 和 Google Search Console 数据（analytics.readonly + webmasters.readonly 作用域）。

新手？ 按照 ONBOARDING.md 进行从零到可用的完整演练（安装 Claude Code、获取凭据、授权、验证）。本文件的其余部分是参考资料。

AI 代理：本文件兼作 AGENTS.md —— 从这里开始进行设置，然后阅读 skills/analyze-ga-gsc/SKILL.md 了解如何使用这些工具（访问检查、默认日期范围、GA4 与 GSC 语义、演示交接格式）。切勿要求用户将凭据粘贴到聊天中。

工具

• analytics_auth_start / analytics_auth_status — 本地 OAuth 流程 + 状态检查

• analytics_list_sources — 列出授权账户可用的 GA4 资源和 GSC 网站

• ga_run_report — 运行 GA4 报告

• gsc_query_search_analytics — 查询 Search Console 数据

• analytics_presentation_snapshot — 用于报告的 GA4 + GSC 组合快照

Related MCP server: BigQuery MCP Server

设置（按用户）

每个用户使用自己的 Google 账户进行授权，并保留自己的本地令牌 —— 切勿在机器之间共享 client_secret.json 机密或 tokens.json。

1. Google Cloud OAuth 客户端：在 Google Cloud Console 中创建（或复用现有的）OAuth 2.0 桌面客户端，并下载其 client_secret.json。如果同意屏幕处于“测试”发布状态，请先将每个新用户的 Google 账户添加为测试用户，否则授权将因访问被拒绝而失败。

2. 放置凭据 到 ~/.config/ga-gsc-analytics/client_secret.json（或将 GA_GSC_CLIENT_SECRET 指向自定义路径）。

3. 授予数据访问权限：授权 Google 账户需要对目标 GA4 资源（Analytics Admin → Property Access Management）和 GSC 网站（Search Console → Settings → Users and permissions）具有实际权限。

4. 构建服务器（仅当您更改 mcp/server.mjs 时才需要；仓库附带预构建的 mcp/server.bundle.cjs）：

pnpm install
pnpm run build   # bundles mcp/server.mjs -> mcp/server.bundle.cjs

5. 注册 MCP 服务器。任选其一：

   • Claude Code，用户级：claude mcp add ga-gsc-analytics -- node /path/to/ga-gsc-analytics/mcp/server.bundle.cjs

   • Claude Code / Codex，项目级：此仓库已附带相对路径的 .mcp.json（{"mcpServers": {"ga_gsc_analytics": {"command": "node", "args": ["./mcp/server.bundle.cjs"]}}}）—— 将其复制到项目中，或符号链接/引入整个文件夹，打开该项目时会自动识别。

6. 授权：在您的 AI 工具中调用 analytics_auth_start 工具 —— 它会打开本地浏览器 OAuth 流程并写入 ~/.config/ga-gsc-analytics/tokens.json。

7. 验证：调用 analytics_auth_status（应报告 authorized: true），然后调用 analytics_list_sources 确认预期的 GA4 资源 / GSC 网站出现。

配置覆盖

开发

pnpm run check   # syntax check
pnpm test        # node --test tests/*.test.mjs