google-analytics-automation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Analytics Automation via Rube MCP

通过Rube MCP实现Google Analytics自动化

Automate Google Analytics 4 (GA4) reporting and property management through Composio's Google Analytics toolkit via Rube MCP.

通过Composio的Google Analytics工具包，借助Rube MCP实现Google Analytics 4（GA4）报告和媒体资源管理的自动化。

Prerequisites

前提条件

Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
Active Google Analytics connection via
```
RUBE_MANAGE_CONNECTIONS
```
with toolkit
```
google_analytics
```
Always call
```
RUBE_SEARCH_TOOLS
```
first to get current tool schemas

必须已连接Rube MCP（RUBE_SEARCH_TOOLS可用）
通过
```
RUBE_MANAGE_CONNECTIONS
```
激活Google Analytics连接，工具包为
```
google_analytics
```
请始终先调用
```
RUBE_SEARCH_TOOLS
```
以获取最新的工具架构

Setup

设置

Get Rube MCP: Add

https://rube.app/mcp

as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.

Verify Rube MCP is available by confirming
```
RUBE_SEARCH_TOOLS
```
responds
Call
```
RUBE_MANAGE_CONNECTIONS
```
with toolkit
```
google_analytics
```
If connection is not ACTIVE, follow the returned auth link to complete Google OAuth
Confirm connection status shows ACTIVE before running any workflows

获取Rube MCP：在客户端配置中添加

https://rube.app/mcp

作为MCP服务器。无需API密钥 — 只需添加端点即可使用。

确认
```
RUBE_SEARCH_TOOLS
```
能正常响应，以此验证Rube MCP可用
调用
```
RUBE_MANAGE_CONNECTIONS
```
，指定工具包为
```
google_analytics
```
如果连接未处于ACTIVE状态，请按照返回的授权链接完成Google OAuth认证
在运行任何工作流之前，确认连接状态显示为ACTIVE

Core Workflows

核心工作流

1. List Accounts and Properties

1. 列出账户和媒体资源

When to use: User wants to discover available GA4 accounts and properties

Tool sequence:

```
GOOGLE_ANALYTICS_LIST_ACCOUNTS
```
- List all accessible GA4 accounts [Required]
```
GOOGLE_ANALYTICS_LIST_PROPERTIES
```
- List properties under an account [Required]

Key parameters:

```
pageSize
```
: Number of results per page
```
pageToken
```
: Pagination token from previous response
```
filter
```
: Filter expression for properties (e.g.,
```
parent:accounts/12345
```
)

Pitfalls:

Property IDs are numeric strings prefixed with 'properties/' (e.g., 'properties/123456')
Account IDs are prefixed with 'accounts/' (e.g., 'accounts/12345')
Always list accounts first, then properties under each account
Pagination required for organizations with many properties

适用场景：用户想要查看可用的GA4账户和媒体资源

工具序列：

```
GOOGLE_ANALYTICS_LIST_ACCOUNTS
```
- 列出所有可访问的GA4账户 [必填]
```
GOOGLE_ANALYTICS_LIST_PROPERTIES
```
- 列出指定账户下的媒体资源 [必填]

关键参数：

```
pageSize
```
：每页返回的结果数量
```
pageToken
```
：上一次响应中的分页令牌
```
filter
```
：媒体资源的过滤表达式（例如：
```
parent:accounts/12345
```
）

注意事项：

媒体资源ID是带有'properties/'前缀的数字字符串（例如：'properties/123456'）
账户ID带有'accounts/'前缀（例如：'accounts/12345'）
请始终先列出账户，再列出每个账户下的媒体资源
对于拥有大量媒体资源的组织，需要使用分页功能

2. Run Standard Reports

2. 运行标准报告

When to use: User wants to query metrics and dimensions from GA4 data

Tool sequence:

```
GOOGLE_ANALYTICS_LIST_PROPERTIES
```
- Get property ID [Prerequisite]
```
GOOGLE_ANALYTICS_GET_METADATA
```
- Discover available dimensions and metrics [Optional]
```
GOOGLE_ANALYTICS_CHECK_COMPATIBILITY
```
- Verify dimension/metric compatibility [Optional]
```
GOOGLE_ANALYTICS_RUN_REPORT
```
- Execute the report query [Required]

Key parameters:

```
property
```
: Property ID (e.g., 'properties/123456')
```
dateRanges
```
: Array of date range objects with
```
startDate
```
and
```
endDate
```
```
dimensions
```
: Array of dimension objects with
```
name
```
field
```
metrics
```
: Array of metric objects with
```
name
```
field
```
dimensionFilter
```
/
```
metricFilter
```
: Filter expressions
```
orderBys
```
: Sort order configuration
```
limit
```
: Maximum rows to return
```
offset
```
: Row offset for pagination

Pitfalls:

Date format is 'YYYY-MM-DD' or relative values like 'today', 'yesterday', '7daysAgo', '30daysAgo'
Not all dimensions and metrics are compatible; use CHECK_COMPATIBILITY first
Use GET_METADATA to discover valid dimension and metric names
Maximum 9 dimensions per report request
Row limit defaults vary; set explicitly for large datasets
```
offset
```
is for result pagination, not date pagination

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

工具序列：

```
GOOGLE_ANALYTICS_LIST_PROPERTIES
```
- 获取媒体资源ID [前提步骤]
```
GOOGLE_ANALYTICS_GET_METADATA
```
- 查看可用的维度和指标 [可选]
```
GOOGLE_ANALYTICS_CHECK_COMPATIBILITY
```
- 验证维度/指标的兼容性 [可选]
```
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. Run Batch Reports

3. 运行批量报告

When to use: User needs multiple different reports from the same property in one call

Tool sequence:

```
GOOGLE_ANALYTICS_LIST_PROPERTIES
```
- Get property ID [Prerequisite]
```
GOOGLE_ANALYTICS_BATCH_RUN_REPORTS
```
- Execute multiple reports at once [Required]

Key parameters:

```
property
```
: Property ID (required)
```
requests
```
: Array of individual report request objects (same structure as RUN_REPORT)

Pitfalls:

Maximum 5 report requests per batch call
All reports in a batch must target the same property
Each individual report has the same dimension/metric limits as RUN_REPORT
Batch errors may affect all reports; check individual report responses

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

工具序列：

```
GOOGLE_ANALYTICS_LIST_PROPERTIES
```
- 获取媒体资源ID [前提步骤]
```
GOOGLE_ANALYTICS_BATCH_RUN_REPORTS
```
- 同时执行多个报告 [必填]

关键参数：

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

注意事项：

每次批量调用最多支持5个报告请求
批量中的所有报告必须针对同一媒体资源
每个单独的报告具有与RUN_REPORT相同的维度/指标限制
批量错误可能会影响所有报告；请检查每个报告的响应

4. Run Pivot Reports

4. 运行透视表报告

When to use: User wants cross-tabulated data (rows vs columns) like pivot tables

Tool sequence:

```
GOOGLE_ANALYTICS_LIST_PROPERTIES
```
- Get property ID [Prerequisite]
```
GOOGLE_ANALYTICS_RUN_PIVOT_REPORT
```
- Execute pivot report [Required]

Key parameters:

```
property
```
: Property ID (required)
```
dateRanges
```
: Date range objects
```
dimensions
```
: All dimensions used in any pivot
```
metrics
```
: Metrics to aggregate
```
pivots
```
: Array of pivot definitions with
```
fieldNames
```
,
```
limit
```
, and
```
orderBys
```

Pitfalls:

Dimensions used in pivots must also be listed in top-level
```
dimensions
```
Pivot
```
fieldNames
```
reference dimension names from the top-level list
Complex pivots with many dimensions can produce very large result sets
Each pivot has its own independent
```
limit
```
and
```
orderBys
```

适用场景：用户需要交叉制表数据（行vs列），如透视表

工具序列：

```
GOOGLE_ANALYTICS_LIST_PROPERTIES
```
- 获取媒体资源ID [前提步骤]
```
GOOGLE_ANALYTICS_RUN_PIVOT_REPORT
```
- 执行透视表报告 [必填]

关键参数：

```
property
```
：媒体资源ID（必填）
```
dateRanges
```
：日期范围对象
```
dimensions
```
：所有透视表中使用的维度
```
metrics
```
：要聚合的指标
```
pivots
```
：透视表定义数组，包含
```
fieldNames
```
、
```
limit
```
和
```
orderBys
```

注意事项：

透视表中使用的维度也必须在顶层
```
dimensions
```
中列出
透视表的
```
fieldNames
```
引用顶层列表中的维度名称
包含多个维度的复杂透视表可能会生成非常大的结果集
每个透视表有独立的
```
limit
```
和
```
orderBys
```
配置

5. Run Funnel Reports

5. 运行漏斗报告

When to use: User wants to analyze conversion funnels and drop-off rates

Tool sequence:

```
GOOGLE_ANALYTICS_LIST_PROPERTIES
```
- Get property ID [Prerequisite]
```
GOOGLE_ANALYTICS_RUN_FUNNEL_REPORT
```
- Execute funnel analysis [Required]

Key parameters:

```
property
```
: Property ID (required)
```
dateRanges
```
: Date range objects
```
funnel
```
: Funnel definition with
```
steps
```
array
```
funnelBreakdown
```
: Optional dimension to break down funnel by

Pitfalls:

Funnel steps are ordered; each step defines a condition users must meet
Steps use filter expressions similar to dimension/metric filters
Open funnels allow entry at any step; closed funnels require sequential progression
Funnel reports may take longer to process than standard reports

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

工具序列：

```
GOOGLE_ANALYTICS_LIST_PROPERTIES
```
- 获取媒体资源ID [前提步骤]
```
GOOGLE_ANALYTICS_RUN_FUNNEL_REPORT
```
- 执行漏斗分析 [必填]

关键参数：

```
property
```
：媒体资源ID（必填）
```
dateRanges
```
：日期范围对象
```
funnel
```
：漏斗定义，包含
```
steps
```
数组
```
funnelBreakdown
```
：可选维度，用于细分漏斗数据

注意事项：

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

6. Manage Key Events

6. 管理关键事件

When to use: User wants to view or manage conversion events (key events) in GA4

Tool sequence:

```
GOOGLE_ANALYTICS_LIST_PROPERTIES
```
- Get property ID [Prerequisite]
```
GOOGLE_ANALYTICS_LIST_KEY_EVENTS
```
- List all key events for the property [Required]

Key parameters:

```
parent
```
: Property resource name (e.g., 'properties/123456')
```
pageSize
```
: Number of results per page
```
pageToken
```
: Pagination token

Pitfalls:

Key events were previously called "conversions" in GA4
Property must have key events configured to return results
Key event names correspond to GA4 event names

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

工具序列：

```
GOOGLE_ANALYTICS_LIST_PROPERTIES
```
- 获取媒体资源ID [前提步骤]
```
GOOGLE_ANALYTICS_LIST_KEY_EVENTS
```
- 列出该媒体资源的所有关键事件 [必填]

关键参数：

```
parent
```
：媒体资源的资源名称（例如：'properties/123456'）
```
pageSize
```
：每页返回的结果数量
```
pageToken
```
：分页令牌

注意事项：

关键事件在GA4中以前被称为"转化事件"
只有配置了关键事件的媒体资源才会返回结果
关键事件名称与GA4事件名称对应

Common Patterns

常见模式

ID Resolution

ID解析

Account name -> Account ID:

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

Property name -> Property ID:

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

账户名称 -> 账户ID：

1. 调用GOOGLE_ANALYTICS_LIST_ACCOUNTS
2. 通过displayName查找账户
3. 提取name字段（例如：'accounts/12345'）

媒体资源名称 -> 媒体资源ID：

1. 调用带filter参数的GOOGLE_ANALYTICS_LIST_PROPERTIES
2. 通过displayName查找媒体资源
3. 提取name字段（例如：'properties/123456'）

Dimension/Metric Discovery

维度/指标发现

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

1. 使用媒体资源ID调用GOOGLE_ANALYTICS_GET_METADATA
2. 浏览可用的维度和指标
3. 调用GOOGLE_ANALYTICS_CHECK_COMPATIBILITY验证组合是否有效
4. 在RUN_REPORT中使用已验证的维度/指标

Pagination

分页

Reports: Use
```
offset
```
and
```
limit
```
for row pagination
Accounts/Properties: Use
```
pageToken
```
from response
Continue until
```
pageToken
```
is absent or
```
rowCount
```
reached

报告：使用
```
offset
```
和
```
limit
```
进行行分页
账户/媒体资源：使用响应中的
```
pageToken
```
持续调用直到
```
pageToken
```
不存在或达到
```
rowCount
```

Common Dimensions and Metrics

常见维度和指标

Dimensions:

date

city

country

deviceCategory

sessionSource

sessionMedium

pagePath

pageTitle

eventName

Metrics:

activeUsers

sessions

screenPageViews

eventCount

conversions

totalRevenue

bounceRate

averageSessionDuration

维度：

date

city

country

deviceCategory

sessionSource

sessionMedium

pagePath

pageTitle

eventName

指标：

activeUsers

sessions

screenPageViews

eventCount

conversions

totalRevenue

bounceRate

averageSessionDuration

Known Pitfalls

已知注意事项

Property IDs:

Always use full resource name format: 'properties/123456'
Numeric ID alone will cause errors
Resolve property names to IDs via LIST_PROPERTIES

Date Ranges:

Format: 'YYYY-MM-DD' or relative ('today', 'yesterday', '7daysAgo', '30daysAgo')
Data processing delay means today's data may be incomplete
Maximum date range varies by property configuration

Compatibility:

Not all dimensions work with all metrics
Always verify with CHECK_COMPATIBILITY before complex reports
Custom dimensions/metrics have specific naming patterns

Response Parsing:

Report data is nested in
```
rows
```
array with
```
dimensionValues
```
and
```
metricValues
```
Values are returned as strings; parse numbers explicitly
Empty reports return no
```
rows
```
key (not an empty array)

媒体资源ID：

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

日期范围：

格式：'YYYY-MM-DD'或相对值（'today'、'yesterday'、'7daysAgo'、'30daysAgo'）
数据处理延迟意味着当日数据可能不完整
最大日期范围因媒体资源配置而异

兼容性：

并非所有维度都能与所有指标搭配使用
在生成复杂报告前，请始终使用CHECK_COMPATIBILITY验证
自定义维度/指标有特定的命名规则

响应解析：

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

Quick Reference

快速参考

Task	Tool Slug	Key Params
List accounts	GOOGLE_ANALYTICS_LIST_ACCOUNTS	pageSize, pageToken
List properties	GOOGLE_ANALYTICS_LIST_PROPERTIES	filter, pageSize
Get metadata	GOOGLE_ANALYTICS_GET_METADATA	property
Check compatibility	GOOGLE_ANALYTICS_CHECK_COMPATIBILITY	property, dimensions, metrics
Run report	GOOGLE_ANALYTICS_RUN_REPORT	property, dateRanges, dimensions, metrics
Batch reports	GOOGLE_ANALYTICS_BATCH_RUN_REPORTS	property, requests
Pivot report	GOOGLE_ANALYTICS_RUN_PIVOT_REPORT	property, dateRanges, pivots
Funnel report	GOOGLE_ANALYTICS_RUN_FUNNEL_REPORT	property, dateRanges, funnel
List key events	GOOGLE_ANALYTICS_LIST_KEY_EVENTS	parent, pageSize

任务	工具标识	关键参数
列出账户	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