如何把 GA4 数据接入 AI 助手，
随时查访问与关键词。

GA4 装了三年，报表打开过三次，这大概是多数外贸站的状态。数据没问题，麻烦的是每次都要「登录 → 选媒体资源 → 选日期 → 拼维度」。MCP 可以把这一段省掉：AI 客户端连上它之后，你在对话框里问一句，它自己去调 GA4 把数拿回来。下面用 WorkBuddy 和 Codex 举例，同一个 server，两处配置写法，半小时左右能配完。关键词那部分也一起说清楚。

一、MCP 是什么，为什么值得花半小时装上？

MCP 是 Model Context Protocol，一个让 AI 客户端调用外部工具的开放协议。你不需要理解协议细节，只要知道两件事：

第一，MCP server 是一个跑在本机的小程序，它替你保管凭据、替你调接口。第二，AI 客户端（WorkBuddy、Codex、Claude Code、Cursor 这类）连上它之后，就能把这些能力当成工具来用。

server 是同一个，客户端只是用不同的格式把它写进配置。所以学会一次就够，换客户端只换配置文件的写法，第四节会把 JSON 和 TOML 两种都写出来。

落到 GA4 上，好处很具体。以前想查「上周自然搜索哪个落地页掉得最狠」，得进后台、拉报告、导表格、自己比对两周。现在问一句，它调两次接口，把两行数字摆出来。省下的不是几分钟，是这件事你以前根本不会去做。

二、官方这个 server 能读什么，不能读什么？

先看清边界，省得配完才发现少了东西。官方仓库只接了 Admin API 和 Data API 两套：

“The server uses the Google Analytics Admin API and the Google Analytics Data API to provide several Tools for use with LLMs.”

README 原话：这个 server 靠 Admin API 和 Data API 提供工具。也就是说，它读的是 GA4 自己的数据，不是 Search Console 的原始查询表。第五节会讲，这为什么不影响你要看的东西。

GitHub · googleanalytics/google-analytics-mcp

仓库地址：https://github.com/googleanalytics/google-analytics-mcp。它是 experimental 状态，工具还会加，配之前扫一眼 README 最稳。

三、环境依赖，能不能让 AI 自己装？

能。README 里要装的东西三样：Python 3.10 以上、pipx、gcloud CLI。前两个让 server 跑起来，第三个用来登录。这三样自己装要折腾一会儿，很多人就卡在这里。

省事的办法是把仓库地址直接发给 AI，让它自己读 README、自己检查缺什么、自己装。在 WorkBuddy 或 Codex 里新开一个会话，把下面这段发过去：

读一下 https://github.com/googleanalytics/google-analytics-mcp 的 README，
按它的要求把这台机器的环境配好：
1. 查 python3 版本，低于 3.10 就告诉我怎么升，不要动系统自带的 Python
2. 查 pipx 和 uvx，缺哪个用 brew 装上
3. 查 gcloud 有没有装、有没有登录过
4. 装完跑一次 pipx install analytics-mcp，确认包能起来
每条命令先给我看，我确认后再执行；报错就贴原文，不要猜着换方案。

让它执行前先把命令发给你看。装这些东西会改动系统目录，装错了不好恢复。你看命令的时候只要判断一件事：动的是你自己的环境，还是系统里的公共部分。

有三件事 AI 做不了，得你自己来：在 Google Cloud 控制台开两个 API、创建 OAuth 客户端、在浏览器里点同意。这三步都涉及账号权限，需要本人操作。

另外，凭据文件的路径可以让它读，文件内容不要让它复制到对话里。里面是长期有效的令牌，贴进聊天记录就多了一次外泄的机会。

依赖装好之后不用关会话，接着让它按下面的四步继续配。它已经知道你的 Python 和 pipx 装在哪，能省不少来回解释。

四、四步配完，AI 就能报数了吗？

能。一共四步，都在命令行和配置文件里完成。

第 1 步：建项目、开两个 API。Google Cloud 控制台新建一个项目（用你平时登录 GA4 的那个 Google 账号），然后在 API 库里启用「Google Analytics Admin API」和「Google Analytics Data API」。少开一个，后面第一次调用就会 403。

建完项目、开了接口，在「API 和服务 → 流量」里能看到每个接口的调用曲线。这张图是刚配好、还没跑过查询的状态：三条线都是平的。以后调不通，先看这里——是零调用（压根没配对），还是有调用但报错（权限或 scope 的问题）。图上三条分别对应 Admin API（列账号和媒体资源）、Data API（跑报表）和 Search Console API——最后这个官方 server 用不到，顺手开的，留着不碍事。

第 2 步：配应用默认凭据。在装了 gcloud 的机器上跑：

gcloud auth application-default login \
  --scopes https://www.googleapis.com/auth/analytics.readonly,\
https://www.googleapis.com/auth/cloud-platform \
  --client-id-file=你的OAuth客户端JSON

# 跑完会打印凭据路径，下一步要用
# Credentials saved to file: [PATH_TO_CREDENTIALS_JSON]

两个细节容易漏。scope 里除了 analytics.readonly，还得带上 cloud-platform，否则 ADC 建不起来。另外 --client-id-file 指向的是 OAuth 桌面客户端 JSON，不是服务账号密钥，官方示例走的也是这条路。

第 3 步：写进客户端配置。先看 WorkBuddy：文件在 ~/.workbuddy/mcp.json，把 server 加进 mcpServers：

{
  "mcpServers": {
    "analytics-mcp": {
      "command": "uvx",
      "args": ["--from", "analytics-mcp", "google-analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_CLOUD_PROJECT": "你的项目ID"
      }
    }
  }
}

上面用的是 uvx。官方 README 推荐的是 pipx，装过 pipx 就改成 "command": "pipx"、"args": ["run", "analytics-mcp"]，效果一样，还省得每次写包名和入口名。GOOGLE_CLOUD_PROJECT 建议写上，配额和计费都挂在这个项目上。

Codex 读的是 TOML，不是 JSON，文件在 ~/.codex/config.toml。同一个 server，改写成表结构，环境变量单独一段：

[mcp_servers.analytics-mcp]
command = "uvx"
args = ["--from", "analytics-mcp", "google-analytics-mcp"]

[mcp_servers.analytics-mcp.env]
GOOGLE_APPLICATION_CREDENTIALS = "PATH_TO_CREDENTIALS_JSON"
GOOGLE_CLOUD_PROJECT = "你的项目ID"

两个客户端可以同时接，不用二选一。它们各自起一个进程，读的是同一份凭据。Codex 那边也可以不手写，用 codex mcp add 直接写进配置，再用 codex mcp list 看有没有连上。客户端的配置格式改得比较勤，动手前看一眼各自的官方文档。

第 4 步：信任，再问一句验证。WorkBuddy 改完配置重启，在连接器列表里给这个 server 点一次「信任」，不点不会启用。Codex 用 codex mcp list 看服务状态。验证问题两边一样：「我有哪些 GA4 媒体资源」，能列出账号和属性（property）就算通了。

五、为什么 GSC 不用再单独授权？

这是配这套东西时最常见的分歧点。网上很多教程写到一半会说：还要去看 Search Console 数据，得再启用 Search Console API、再加一个 webmasters scope、再配一个 server。听起来像要开第二套账号体系。

实际上不用。前提是你的 GA4 媒体资源已经和 Search Console 关联过，做过 SEO 的站一般都已经关联了。关联之后，自然搜索的落地页、国家、设备、转化，在 GA4 里本来就是普通维度，用 run_report 直接查：

维度：sessionDefaultChannelGroup, landingPage, country, deviceCategory
指标：sessions, engagedSessions, keyEvents
筛选：sessionDefaultChannelGroup = Organic Search

「上周自然搜索哪个落地页跌了」这类问题，一次 analytics.readonly 授权就够了，GSC 那边不用再交一次权限。跟 GA4 后台关联 Search Console 是同一件事，只是现在能从对话框里问。

关联之后，Data API 里多出来的是一组带「需要有效 Search Console 关联」标注的指标：organicGoogleSearchClicks（自然点击）、organicGoogleSearchImpressions（展示）、organicGoogleSearchClickThroughRate（点击率）、organicGoogleSearchAveragePosition（平均排名）。

但有个区别要注意：这四个都是指标，不是维度。所以「哪个页面从自然搜索拿到了点击、平均排第几」答得上来，「用户搜的什么词」答不上来，Data API 的公开维度表里没有搜索词这个字段。那些词在 GA4 后台的「查询」报表里能看到（第六节有截图），接口不返回。关键词要单独补一层，第八节讲。

六、GA4 里那条关联，最初是在哪配的？

如果还没关联过，现在补也来得及。路径是：GA4 后台 → 管理 → 产品关联 → Search Console 关联 → 点「关联」→ 选你的 Search Console 资源 → 选网站数据流 → 确认。关联成功后，左侧导航会多出一个 Search Console 分组：

有三件事值得提前知道，都是关联之后才发现的：

一是数据不回溯。Google 的说明是 Search Console 完成数据收集 48 小时后数据才可用，而起点取「建数据流」和「完成网站验证」两者中较晚的那个。今天关联，只能看到今天之后的数据，去年的排名历史不会补进来。

二是一个数据流只能关联一个 Search Console 资源，反过来也一样。选错了要删掉重建，重建之后所有日期范围的报表都会改用新的数据流。

三是关联需要 GA4 的「编辑者」权限加 Search Console 的「已验证所有者」身份。只有查看权限的同事做不了这一步，得找对人。

七、配好之后，访问数据能问到多细？

工具本身很简单，好处是能随口问。下面这些是我用得最多的，都是「站上发生了什么」这一类：

提问方式也变了。以前先想「后台哪张报表有这个东西」，现在先想「我想知道什么」，让它去挑维度和指标。写错了它会报错，这时看一眼维度名，顺便把口径也理清了。

表里前几行和后三行的数据来源不同。点击、展示、平均排名来自 Search Console 的关联，会话、落地页、漏斗是 GA4 自己记的。一个是搜索结果页上发生的事，一个是人到了你站上之后做的事，可以对着看，别混着比较。

八、关键词情况呢？GA4 能给出哪一层？

配完之后，被问得最多的就是这句。答案分两层。

第一层：具体是哪些词，GA4 后台看得到，接口拿不到。关联 Search Console 之后，左侧会多出「查询」报表（第六节那张截图），里面就是搜索词、展示、点击、排名。但这些词没有进 Data API 的公开维度表，所以在对话框里问「上周哪些词带来了点击」，它只能按落地页、国家给你结果，给不出词表。不是配错了，是接口没有这个字段。

第二层：要看词，就再配一个接 Search Console 的 server。Search Console 有独立 API，查询走这一个端点：

POST https://www.googleapis.com/webmasters/v3/sites/{siteUrl}/searchAnalytics/query

授权用 webmasters.readonly。同一个 Cloud 项目、同一个 Google 账号，加这个 scope 就行，不需要另注册账号，也不用另开一套凭据。网上很多教程把这里说得很复杂，其实就是多一个 scope、多一个 server。社区里有现成的 Search Console MCP server，挑维护活跃的用；如果只要「按维度拉词表」这一件事，自己写一个几十行的薄 server 更好控制。

有两个限制要知道。单次查询最多返回 25,000 行，默认只有 1,000 行，按点击排序取前面的；每天每种搜索类型还有 5 万行的总额度。看几十上百个词够用，想一次拉全站历史就不合适，那种情况应该按页面或按周分批问。

两层不冲突。点击、展示、排名走 GA4，一次 analytics.readonly 就够；搜什么词走 Search Console API，多配一个 server。别指望一个授权拿到全部，也别为了看几个词把已经跑通的部分重做。

九、踩过哪些坑？

配了不止一次，下面几条是按踩到的顺序记的：

凭据对，但读不到数据。ADC 里那个 Google 账号必须对该 GA4 媒体资源有权限，否则接口会干净地返回空结果或 403。用服务账号时更要注意：得把服务账号邮箱加进媒体资源的用户列表，光有密钥文件不够。

JSON 写进了 git。凭据文件里是长期有效的刷新令牌，泄了等于把整个 GA4 的读权限交出去。这个文件放家目录，别放项目目录，更别提交。

TOML 里一个引号写错，整组 server 都不出来。Codex 的配置文件只要有一处格式不合法，可能连别的 server 一起加载失败。排查时把条目一个个注释掉，比反复改命令快。

第一次调用特别慢。uvx 或 pipx 在首次运行时会拉包建环境，几十秒很正常。之后就快了，不是它没反应，是在装依赖。

要不要开 --allow-write。不用。写工具目前只有「创建报表注释」这类，日常分析用不到。只读权限够，出了问题损失也小。

十、这套东西的边界在哪？

说三个限制，别把它当成万能工具。

第一，它只是把手动点报表变成一句话，替代不了判断。数据告诉你某个落地页掉了，为什么掉，还得人去看那个页面改了什么。

第二，GA4 的数据本身有延迟，也有口径问题（会话与用户、归因窗口、内部流量过滤）。MCP 拿到的是「GA4 里的数」，不是「真实世界的数」，两者之间的差距不会因为这层自动化而缩小。

第三，它取代不了 Search Console。关键词、抓取、索引这些事，还是得在 GSC 里看。只是平时看一眼自然搜索，不用再多开一套授权。

我的看法是：不用为它专门学一门技术，但值得花半小时装上。装完之后，你会开始问以前懒得问的问题。