amplitude-automation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Amplitude Automation via Rube MCP

通过Rube MCP实现Amplitude自动化

Automate Amplitude product analytics through Composio's Amplitude toolkit via Rube MCP.

借助Composio的Amplitude工具包，通过Rube MCP实现Amplitude产品分析的自动化操作。

Prerequisites

前提条件

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

必须已连接Rube MCP（需确保
```
RUBE_SEARCH_TOOLS
```
可用）
通过
```
RUBE_MANAGE_CONNECTIONS
```
并使用工具包
```
amplitude
```
建立有效的Amplitude连接
请始终先调用
```
RUBE_SEARCH_TOOLS
```
获取当前工具的模式（schemas）

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
```
amplitude
```
If connection is not ACTIVE, follow the returned auth link to complete Amplitude authentication
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
```
并指定工具包
```
amplitude
```
如果连接状态未显示为ACTIVE，请按照返回的授权链接完成Amplitude身份验证
在运行任何工作流之前，确认连接状态显示为ACTIVE

Core Workflows

核心工作流

1. Send Events

1. 发送事件

When to use: User wants to track events or send event data to Amplitude

Tool sequence:

```
AMPLITUDE_SEND_EVENTS
```
- Send one or more events to Amplitude [Required]

Key parameters:

```
events
```
: Array of event objects, each containing:
- ```
event_type
```
  : Name of the event (e.g., 'page_view', 'purchase')
- ```
user_id
```
  : Unique user identifier (required if no
```
device_id
```
  )
- ```
device_id
```
  : Device identifier (required if no
```
user_id
```
  )
- ```
event_properties
```
  : Object with custom event properties
- ```
user_properties
```
  : Object with user properties to set
- ```
time
```
  : Event timestamp in milliseconds since epoch

Pitfalls:

At least one of
```
user_id
```
or
```
device_id
```
is required per event
```
event_type
```
is required for every event; cannot be empty
```
time
```
must be in milliseconds (13-digit epoch), not seconds
Batch limit applies; check schema for maximum events per request
Events are processed asynchronously; successful API response does not mean data is immediately queryable

适用场景：用户需要跟踪事件或向Amplitude发送事件数据

工具调用流程:

```
AMPLITUDE_SEND_EVENTS
```
- 向Amplitude发送一个或多个事件 [必填]

关键参数:

```
events
```
: 事件对象数组，每个对象包含：
- ```
event_type
```
  : 事件名称（例如：'page_view'、'purchase'）
- ```
user_id
```
  : 唯一用户标识符（若未提供
```
device_id
```
  则为必填）
- ```
device_id
```
  : 设备标识符（若未提供
```
user_id
```
  则为必填）
- ```
event_properties
```
  : 包含自定义事件属性的对象
- ```
user_properties
```
  : 用于设置用户属性的对象
- ```
time
```
  : 事件时间戳（自纪元以来的毫秒数）

常见陷阱:

每个事件至少需要
```
user_id
```
或
```
device_id
```
中的一个
每个事件的
```
event_type
```
为必填项，不能为空
```
time
```
必须以毫秒为单位（13位纪元时间），而非秒
存在批量限制；请查看模式以了解单次请求的最大事件数量
事件为异步处理；API响应成功不代表数据可立即查询

2. Get User Activity

2. 获取用户活动

When to use: User wants to view event history for a specific user

Tool sequence:

```
AMPLITUDE_FIND_USER
```
- Find user by ID or property [Prerequisite]
```
AMPLITUDE_GET_USER_ACTIVITY
```
- Retrieve user's event stream [Required]

Key parameters:

```
user
```
: Amplitude internal user ID (from FIND_USER)
```
offset
```
: Pagination offset for event list
```
limit
```
: Maximum number of events to return

Pitfalls:

```
user
```
parameter requires Amplitude's internal user ID, NOT your application's user_id
Must call FIND_USER first to resolve your user_id to Amplitude's internal ID
Activity is returned in reverse chronological order by default
Large activity histories require pagination via
```
offset
```

适用场景：用户需要查看特定用户的事件历史

工具调用流程:

```
AMPLITUDE_FIND_USER
```
- 通过ID或属性查找用户 [前置步骤]
```
AMPLITUDE_GET_USER_ACTIVITY
```
- 获取用户的事件流 [必填]

关键参数:

```
user
```
: Amplitude内部用户ID（来自FIND_USER的返回结果）
```
offset
```
: 事件列表的分页偏移量
```
limit
```
: 要返回的最大事件数量

常见陷阱:

```
user
```
参数需要Amplitude的内部用户ID，而非您应用的user_id
必须先调用FIND_USER将您的user_id解析为Amplitude的内部ID
默认情况下，活动记录按时间倒序返回
大型活动历史记录需要通过
```
offset
```
进行分页

3. Find and Identify Users

3. 查找与识别用户

When to use: User wants to look up users or set user properties

Tool sequence:

```
AMPLITUDE_FIND_USER
```
- Search for a user by various identifiers [Required]
```
AMPLITUDE_IDENTIFY
```
- Set or update user properties [Optional]

Key parameters:

For FIND_USER:
- ```
user
```
  : Search term (user_id, email, or Amplitude ID)
For IDENTIFY:
- ```
user_id
```
  : Your application's user identifier
- ```
device_id
```
  : Device identifier (alternative to user_id)
- ```
user_properties
```
  : Object with
```
$set
```
  ,
```
$unset
```
  ,
```
$add
```
  ,
```
$append
```
  operations

Pitfalls:

FIND_USER searches across user_id, device_id, and Amplitude ID
IDENTIFY uses special property operations (
```
$set
```
,
```
$unset
```
,
```
$add
```
,
```
$append
```
)
```
$set
```
overwrites existing values;
```
$setOnce
```
only sets if not already set
At least one of
```
user_id
```
or
```
device_id
```
is required for IDENTIFY
User property changes are eventually consistent; not immediate

适用场景：用户需要查找用户或设置用户属性

工具调用流程:

```
AMPLITUDE_FIND_USER
```
- 通过各种标识符搜索用户 [必填]
```
AMPLITUDE_IDENTIFY
```
- 设置或更新用户属性 [可选]

关键参数:

对于FIND_USER:
- ```
user
```
  : 搜索词（user_id、邮箱或Amplitude ID）
对于IDENTIFY:
- ```
user_id
```
  : 您应用的用户标识符
- ```
device_id
```
  : 设备标识符（作为user_id的替代选项）
- ```
user_properties
```
  : 包含
```
$set
```
  、
```
$unset
```
  、
```
$add
```
  、
```
$append
```
  操作的对象

常见陷阱:

FIND_USER会在user_id、device_id和Amplitude ID中进行搜索
IDENTIFY支持特殊的属性操作（
```
$set
```
、
```
$unset
```
、
```
$add
```
、
```
$append
```
）
```
$set
```
会覆盖现有值；
```
$setOnce
```
仅在属性未设置时生效
IDENTIFY至少需要
```
user_id
```
或
```
device_id
```
中的一个
用户属性的更改最终会一致，但并非即时生效

4. Manage Cohorts

4. 管理用户群组

When to use: User wants to list cohorts, view cohort details, or update cohort membership

Tool sequence:

```
AMPLITUDE_LIST_COHORTS
```
- List all saved cohorts [Required]
```
AMPLITUDE_GET_COHORT
```
- Get detailed cohort information [Optional]
```
AMPLITUDE_UPDATE_COHORT_MEMBERSHIP
```
- Add/remove users from a cohort [Optional]
```
AMPLITUDE_CHECK_COHORT_STATUS
```
- Check async cohort operation status [Optional]

Key parameters:

For LIST_COHORTS: No required parameters
For GET_COHORT:
```
cohort_id
```
(from list results)
For UPDATE_COHORT_MEMBERSHIP:
- ```
cohort_id
```
  : Target cohort ID
- ```
memberships
```
  : Object with
```
add
```
  and/or
```
remove
```
  arrays of user IDs
For CHECK_COHORT_STATUS:
```
request_id
```
from update response

Pitfalls:

Cohort IDs are required for all cohort-specific operations
UPDATE_COHORT_MEMBERSHIP is asynchronous; use CHECK_COHORT_STATUS to verify
```
request_id
```
from the update response is needed for status checking
Maximum membership changes per request may be limited; chunk large updates
Only behavioral cohorts support API membership updates

适用场景：用户需要列出群组、查看群组详情或更新群组成员

工具调用流程:

```
AMPLITUDE_LIST_COHORTS
```
- 列出所有已保存的群组 [必填]
```
AMPLITUDE_GET_COHORT
```
- 获取群组的详细信息 [可选]
```
AMPLITUDE_UPDATE_COHORT_MEMBERSHIP
```
- 向群组添加/移除用户 [可选]
```
AMPLITUDE_CHECK_COHORT_STATUS
```
- 检查异步群组操作的状态 [可选]

关键参数:

对于LIST_COHORTS：无必填参数
对于GET_COHORT：
```
cohort_id
```
（来自列表结果）
对于UPDATE_COHORT_MEMBERSHIP:
- ```
cohort_id
```
  : 目标群组ID
- ```
memberships
```
  : 包含
```
add
```
  和/或
```
remove
```
  用户ID数组的对象
对于CHECK_COHORT_STATUS：更新响应中的
```
request_id
```

常见陷阱:

所有群组特定操作都需要群组ID
UPDATE_COHORT_MEMBERSHIP为异步操作；请使用CHECK_COHORT_STATUS验证结果
状态检查需要更新响应中的
```
request_id
```
单次请求的成员变更数量可能有限制；请将大型更新拆分为多个批次
仅行为群组支持通过API更新成员

5. Browse Event Categories

5. 浏览事件分类

When to use: User wants to discover available event types and categories in Amplitude

Tool sequence:

```
AMPLITUDE_GET_EVENT_CATEGORIES
```
- List all event categories [Required]

Key parameters:

No required parameters; returns all configured event categories

Pitfalls:

Categories are configured in Amplitude UI; API provides read access
Event names within categories are case-sensitive
Use these categories to validate event_type values before sending events

适用场景：用户需要发现Amplitude中可用的事件类型和分类

工具调用流程:

```
AMPLITUDE_GET_EVENT_CATEGORIES
```
- 列出所有事件分类 [必填]

关键参数:

无必填参数；返回所有已配置的事件分类

常见陷阱:

分类在Amplitude UI中配置；API仅提供只读访问
分类中的事件名称区分大小写
在发送事件之前，可使用这些分类验证event_type的值

Common Patterns

常见模式

ID Resolution

ID解析

Application user_id -> Amplitude internal ID:

1. Call AMPLITUDE_FIND_USER with user=your_user_id
2. Extract Amplitude's internal user ID from response
3. Use internal ID for GET_USER_ACTIVITY

Cohort name -> Cohort ID:

1. Call AMPLITUDE_LIST_COHORTS
2. Find cohort by name in results
3. Extract id for cohort operations

应用user_id -> Amplitude内部ID:

1. 调用AMPLITUDE_FIND_USER，参数user=your_user_id
2. 从响应中提取Amplitude的内部用户ID
3. 使用内部ID调用GET_USER_ACTIVITY

群组名称 -> 群组ID:

1. 调用AMPLITUDE_LIST_COHORTS
2. 在结果中按名称查找群组
3. 提取ID用于群组操作

User Property Operations

用户属性操作

Amplitude IDENTIFY supports these property operations:

```
$set
```
: Set property value (overwrites existing)
```
$setOnce
```
: Set only if property not already set
```
$add
```
: Increment numeric property
```
$append
```
: Append to list property
```
$unset
```
: Remove property entirely

Example structure:

json

{
  "user_properties": {
    "$set": {"plan": "premium", "company": "Acme"},
    "$add": {"login_count": 1}
  }
}

Amplitude IDENTIFY支持以下属性操作:

```
$set
```
: 设置属性值（覆盖现有值）
```
$setOnce
```
: 仅在属性未设置时生效
```
$add
```
: 递增数值型属性
```
$append
```
: 向列表型属性追加内容
```
$unset
```
: 完全移除属性

示例结构:

json

{
  "user_properties": {
    "$set": {"plan": "premium", "company": "Acme"},
    "$add": {"login_count": 1}
  }
}

Async Operation Pattern

异步操作模式

For cohort membership updates:

1. Call AMPLITUDE_UPDATE_COHORT_MEMBERSHIP -> get request_id
2. Call AMPLITUDE_CHECK_COHORT_STATUS with request_id
3. Repeat step 2 until status is 'complete' or 'error'

对于群组成员更新:

1. 调用AMPLITUDE_UPDATE_COHORT_MEMBERSHIP -> 获取request_id
2. 使用request_id调用AMPLITUDE_CHECK_COHORT_STATUS
3. 重复步骤2，直到状态变为'complete'或'error'

Known Pitfalls

已知陷阱

User IDs:

Amplitude has its own internal user IDs separate from your application's
FIND_USER resolves your IDs to Amplitude's internal IDs
GET_USER_ACTIVITY requires Amplitude's internal ID, not your user_id

Event Timestamps:

Must be in milliseconds since epoch (13 digits)
Seconds (10 digits) will be interpreted as very old dates
Omitting timestamp uses server receive time

Rate Limits:

Event ingestion has throughput limits per project
Batch events where possible to reduce API calls
Cohort membership updates have async processing limits

Response Parsing:

Response data may be nested under
```
data
```
key
User activity returns events in reverse chronological order
Cohort lists may include archived cohorts; check status field
Parse defensively with fallbacks for optional fields

用户ID:

Amplitude有自己的内部用户ID，与您应用的用户ID相互独立
FIND_USER可将您的ID解析为Amplitude的内部ID
GET_USER_ACTIVITY需要Amplitude的内部ID，而非您的user_id

事件时间戳:

必须为自纪元以来的毫秒数（13位）
秒级时间戳（10位）会被解析为非常早的日期
省略时间戳则会使用服务器接收时间

速率限制:

事件 ingestion 每个项目有吞吐量限制
尽可能批量发送事件以减少API调用次数
群组成员更新有异步处理限制

响应解析:

响应数据可能嵌套在
```
data
```
键下
用户活动按时间倒序返回事件
群组列表可能包含已归档的群组；请检查状态字段
解析时需防御性处理，为可选字段设置回退逻辑

Quick Reference

快速参考

Task	Tool Slug	Key Params
Send events	AMPLITUDE_SEND_EVENTS	events (array)
Find user	AMPLITUDE_FIND_USER	user
Get user activity	AMPLITUDE_GET_USER_ACTIVITY	user, offset, limit
Identify user	AMPLITUDE_IDENTIFY	user_id, user_properties
List cohorts	AMPLITUDE_LIST_COHORTS	(none)
Get cohort	AMPLITUDE_GET_COHORT	cohort_id
Update cohort members	AMPLITUDE_UPDATE_COHORT_MEMBERSHIP	cohort_id, memberships
Check cohort status	AMPLITUDE_CHECK_COHORT_STATUS	request_id
List event categories	AMPLITUDE_GET_EVENT_CATEGORIES	(none)

任务	工具标识（Tool Slug）	关键参数
发送事件	AMPLITUDE_SEND_EVENTS	events（数组）
查找用户	AMPLITUDE_FIND_USER	user
获取用户活动	AMPLITUDE_GET_USER_ACTIVITY	user, offset, limit
识别用户	AMPLITUDE_IDENTIFY	user_id, user_properties
列出群组	AMPLITUDE_LIST_COHORTS	无
获取群组详情	AMPLITUDE_GET_COHORT	cohort_id
更新群组成员	AMPLITUDE_UPDATE_COHORT_MEMBERSHIP	cohort_id, memberships
检查群组操作状态	AMPLITUDE_CHECK_COHORT_STATUS	request_id
列出事件分类	AMPLITUDE_GET_EVENT_CATEGORIES	无