google-analytics-automation

通过 Rube MCP 自动化 Google Analytics

通过 Rube MCP 使用 Composio 的 Google Analytics 工具包，自动执行 Google Analytics 4（GA4）报告和媒体资源管理。

工具包文档：composio.dev/toolkits/google_analytics

前提条件

• 必须已连接 Rube MCP（RUBE_SEARCH_TOOLS 可用）
• 通过 RUBE_MANAGE_CONNECTIONS 建立有效的 Google Analytics 连接，并使用工具包 google_analytics
• 始终先调用 RUBE_SEARCH_TOOLS，以获取当前工具架构

设置

获取 Rube MCP：在客户端配置中将 https://rube.app/mcp 添加为 MCP 服务。无需 API 密钥——只需添加端点即可使用。

1. 确认 RUBE_SEARCH_TOOLS 有响应，以验证 Rube MCP 是否可用
2. 使用工具包 google_analytics 调用 RUBE_MANAGE_CONNECTIONS
3. 如果连接状态不是 ACTIVE，请按照返回的授权链接完成 Google OAuth
4. 在运行任何工作流之前，确认连接状态为 ACTIVE

核心工作流

1. 列出账号和媒体资源

使用场景：用户想要查找可用的 GA4 账号和媒体资源

工具调用顺序：

1. GOOGLE_ANALYTICS_LIST_ACCOUNTS - 列出所有可访问的 GA4 账号［必需］
2. GOOGLE_ANALYTICS_LIST_PROPERTIES - 列出账号下的媒体资源［必需］

关键参数：

• pageSize：每页结果数
• pageToken：上一条响应中的分页令牌
• filter：媒体资源的筛选表达式（例如 parent:accounts/12345）

注意事项：

• 媒体资源 ID 是带有 properties/ 前缀的数字字符串（例如 properties/123456）
• 账号 ID 带有 accounts/ 前缀（例如 accounts/12345）
• 始终先列出账号，再列出每个账号下的媒体资源
• 媒体资源较多的组织需要分页

2. 运行标准报告

使用场景：用户想要查询 GA4 数据中的指标和维度

工具调用顺序：

1. GOOGLE_ANALYTICS_LIST_PROPERTIES - 获取媒体资源 ID［前置步骤］
2. GOOGLE_ANALYTICS_GET_METADATA - 查找可用的维度和指标［可选］
3. GOOGLE_ANALYTICS_CHECK_COMPATIBILITY - 验证维度和指标的兼容性［可选］
4. GOOGLE_ANALYTICS_RUN_REPORT - 执行报告查询［必需］

关键参数：

• property：媒体资源 ID（例如 properties/123456）
• dateRanges：日期范围对象数组，包含 startDate 和 endDate
• dimensions：维度对象数组，包含 name 字段
• metrics：指标对象数组，包含 name 字段
• dimensionFilter / metricFilter：筛选表达式
• orderBys：排序顺序配置
• limit：要返回的最大行数
• offset：分页的行偏移量

注意事项：

• 日期格式为 YYYY-MM-DD，也可以使用 today、yesterday、7daysAgo、30daysAgo 等相对值
• 并非所有维度和指标都兼容；请先使用 CHECK_COMPATIBILITY
• 使用 GET_METADATA 查找有效的维度和指标名称
• 每个报告请求最多包含 9 个维度
• 行数限制的默认值各不相同；对于大型数据集，请显式设置
• offset 用于结果分页，而非日期分页

3. 运行批量报告

使用场景：用户需要在一次调用中获取同一媒体资源的多个不同报告

工具调用顺序：

1. GOOGLE_ANALYTICS_LIST_PROPERTIES - 获取媒体资源 ID［前置步骤］
2. GOOGLE_ANALYTICS_BATCH_RUN_REPORTS - 一次执行多个报告［必需］

关键参数：

• property：媒体资源 ID（必需）
• requests：单个报告请求对象数组（结构与 RUN_REPORT 相同）

注意事项：

• 每次批量调用最多包含 5 个报告请求
• 批次中的所有报告必须针对同一媒体资源
• 每个报告的维度和指标限制与 RUN_REPORT 相同
• 批量调用出错可能会影响所有报告；请检查每个报告的响应

4. 运行透视报告

适用场景：用户需要交叉汇总的数据（行与列），类似数据透视表

工具调用顺序：

1. GOOGLE_ANALYTICS_LIST_PROPERTIES - 获取属性 ID [前置条件]
2. GOOGLE_ANALYTICS_RUN_PIVOT_REPORT - 执行透视报告 [必需]

关键参数：

• property：属性 ID（必需）
• dateRanges：日期范围对象
• dimensions：所有透视中使用的维度
• metrics：要汇总的指标
• pivots：透视定义数组，包含 fieldNames、limit 和 orderBys

注意事项：

• 透视中使用的维度也必须列在顶层的 dimensions 中
• 透视的 fieldNames 引用顶层列表中的维度名称
• 包含多个维度的复杂透视可能产生非常大的结果集
• 每个透视都有各自独立的 limit 和 orderBys

5. 运行漏斗报告

适用场景：用户需要分析转化漏斗和流失率

工具调用顺序：

1. GOOGLE_ANALYTICS_LIST_PROPERTIES - 获取属性 ID [前置条件]
2. GOOGLE_ANALYTICS_RUN_FUNNEL_REPORT - 执行漏斗分析 [必需]

关键参数：

• property：属性 ID（必需）
• dateRanges：日期范围对象
• funnel：包含 steps 数组的漏斗定义
• funnelBreakdown：可选维度，用于拆分漏斗

注意事项：

• 漏斗步骤按顺序排列；每个步骤都定义了用户必须满足的条件
• 步骤使用类似维度/指标过滤器的筛选表达式
• 开放式漏斗允许从任意步骤进入；封闭式漏斗要求按顺序逐步推进
• 漏斗报告的处理时间可能比标准报告更长

6. 管理关键事件

适用场景：用户需要查看或管理 GA4 中的转化事件（关键事件）

工具调用顺序：

1. GOOGLE_ANALYTICS_LIST_PROPERTIES - 获取属性 ID [前置条件]
2. GOOGLE_ANALYTICS_LIST_KEY_EVENTS - 列出该属性的所有关键事件 [必需]

关键参数：

• parent：属性资源名称（例如，'properties/123456'）
• pageSize：每页结果数
• pageToken：分页令牌

注意事项：

• 关键事件在 GA4 中以前称为“转化”
• 属性必须已配置关键事件才能返回结果
• 关键事件名称与 GA4 事件名称对应

常见模式

ID 解析

账户名称 -> 账户 ID：

1. Call GOOGLE_ANALYTICS_LIST_ACCOUNTS
2. Find account by displayName
3. Extract name field (e.g., 'accounts/12345')

属性名称 -> 属性 ID：

1. Call GOOGLE_ANALYTICS_LIST_PROPERTIES with filter
2. Find property by displayName
3. Extract name field (e.g., 'properties/123456')

维度/指标发现

1. Call GOOGLE_ANALYTICS_GET_METADATA with property ID
2. Browse available dimensions and metrics
3. Call GOOGLE_ANALYTICS_CHECK_COMPATIBILITY to verify combinations
4. Use verified dimensions/metrics in RUN_REPORT

分页

• 报告：使用 offset 和 limit 对行进行分页
• 账户/属性：使用响应中的 pageToken
• 持续获取，直到没有 pageToken 或达到 rowCount

常用维度和指标

维度：date、city、country、deviceCategory、sessionSource、sessionMedium、pagePath、pageTitle、eventName

指标：activeUsers、sessions、screenPageViews、eventCount、conversions、totalRevenue、bounceRate、averageSessionDuration

已知注意事项

属性 ID：

• 始终使用完整的资源名称格式：'properties/123456'
• 仅使用数字 ID 会导致错误
• 通过 LIST_PROPERTIES 将属性名称解析为 ID

日期范围：

• 格式：'YYYY-MM-DD' 或相对日期（'today'、'yesterday'、'7daysAgo'、'30daysAgo'）
• 由于数据处理延迟，今天的数据可能不完整
• 最大日期范围因属性配置而异

兼容性：

• 并非所有维度都适用于所有指标
• 复杂报告执行前，始终使用 CHECK_COMPATIBILITY 进行验证
• 自定义维度/指标有特定的命名模式

响应解析：

• 报告数据嵌套在 rows 数组中，其中包含 dimensionValues 和 metricValues
• 返回的值均为字符串；需要显式解析数值
• 空报告不会返回 rows 键（而不是返回空数组）

快速参考

任务	工具标识	关键参数
列出账号	GOOGLE_ANALYTICS_LIST_ACCOUNTS	pageSize, pageToken
列出媒体资源	GOOGLE_ANALYTICS_LIST_PROPERTIES	filter, pageSize
获取元数据	GOOGLE_ANALYTICS_GET_METADATA	property
检查兼容性	GOOGLE_ANALYTICS_CHECK_COMPATIBILITY	property, dimensions, metrics
运行报告	GOOGLE_ANALYTICS_RUN_REPORT	property, dateRanges, dimensions, metrics
批量运行报告	GOOGLE_ANALYTICS_BATCH_RUN_REPORTS	property, requests
透视报告	GOOGLE_ANALYTICS_RUN_PIVOT_REPORT	property, dateRanges, pivots
漏斗报告	GOOGLE_ANALYTICS_RUN_FUNNEL_REPORT	property, dateRanges, funnel
列出关键事件	GOOGLE_ANALYTICS_LIST_KEY_EVENTS	parent, pageSize

---

由 Composio 提供支持