posthog-automation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PostHog Automation via Rube MCP

通过Rube MCP实现PostHog自动化

Automate PostHog product analytics and feature flag management through Composio's PostHog toolkit via Rube MCP.

Toolkit docs: composio.dev/toolkits/posthog

通过Composio的PostHog工具包，借助Rube MCP自动化PostHog产品分析与功能标志管理。

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

Prerequisites

前提条件

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

必须已连接Rube MCP（需确保RUBE_SEARCH_TOOLS可用）
通过
```
RUBE_MANAGE_CONNECTIONS
```
激活PostHog连接，且关联工具包为
```
posthog
```
请始终先调用
```
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
```
posthog
```
If connection is not ACTIVE, follow the returned auth link to complete PostHog 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
```
并指定工具包为
```
posthog
```
如果连接状态未显示为ACTIVE，请按照返回的授权链接完成PostHog身份验证
在运行任何工作流之前，确认连接状态已显示为ACTIVE

Core Workflows

核心工作流

1. Capture Events

1. 捕获事件

When to use: User wants to send event data to PostHog for analytics tracking

Tool sequence:

```
POSTHOG_CAPTURE_EVENT
```
- Send one or more events to PostHog [Required]

Key parameters:

```
event
```
: Event name (e.g., '$pageview', 'user_signed_up', 'purchase_completed')
```
distinct_id
```
: Unique user identifier (required)
```
properties
```
: Object with event-specific properties
```
timestamp
```
: ISO 8601 timestamp (optional; defaults to server time)

Pitfalls:

```
distinct_id
```
is required for every event; identifies the user/device
PostHog system events use
```
$
```
prefix (e.g., '$pageview', '$identify')
Custom events should NOT use the
```
$
```
prefix
Properties are freeform; maintain consistent schemas across events
Events are processed asynchronously; ingestion delay is typically seconds

适用场景：用户需要将事件数据发送至PostHog以进行分析追踪

工具调用流程：

```
POSTHOG_CAPTURE_EVENT
```
- 向PostHog发送一个或多个事件 [必填]

关键参数：

```
event
```
：事件名称（例如：'$pageview'、'user_signed_up'、'purchase_completed'）
```
distinct_id
```
：唯一用户标识符（必填）
```
properties
```
：包含事件特定属性的对象
```
timestamp
```
：ISO 8601格式的时间戳（可选；默认使用服务器时间）

注意事项：

每个事件都必须填写
```
distinct_id
```
，用于标识用户/设备
PostHog系统事件使用
```
$
```
前缀（例如：'$pageview'、'$identify'）
自定义事件不得使用
```
$
```
前缀
属性为自由格式，需在所有事件中保持一致的架构
事件为异步处理；数据摄入延迟通常为几秒

2. List and Filter Events

2. 列出与筛选事件

When to use: User wants to browse or search through captured events

Tool sequence:

```
POSTHOG_LIST_AND_FILTER_PROJECT_EVENTS
```
- Query events with filters [Required]

Key parameters:

```
project_id
```
: PostHog project ID (required)
```
event
```
: Filter by event name
```
person_id
```
: Filter by person ID
```
after
```
: Events after this ISO 8601 timestamp
```
before
```
: Events before this ISO 8601 timestamp
```
limit
```
: Maximum events to return
```
offset
```
: Pagination offset

Pitfalls:

```
project_id
```
is required; resolve via LIST_PROJECTS first
Date filters use ISO 8601 format (e.g., '2024-01-15T00:00:00Z')
Large event volumes require pagination; use
```
offset
```
and
```
limit
```
Results are returned in reverse chronological order by default
Event properties are nested; parse carefully

适用场景：用户需要浏览或搜索已捕获的事件

工具调用流程：

```
POSTHOG_LIST_AND_FILTER_PROJECT_EVENTS
```
- 使用筛选条件查询事件 [必填]

关键参数：

```
project_id
```
：PostHog项目ID（必填）
```
event
```
：按事件名称筛选
```
person_id
```
：按用户ID筛选
```
after
```
：此ISO 8601时间戳之后的事件
```
before
```
：此ISO 8601时间戳之前的事件
```
limit
```
：返回的最大事件数量
```
offset
```
：分页偏移量

注意事项：

```
project_id
```
为必填项；需先通过LIST_PROJECTS获取
日期筛选需使用ISO 8601格式（例如：'2024-01-15T00:00:00Z'）
大量事件需使用分页；请使用
```
offset
```
和
```
limit
```
参数
默认按时间倒序返回结果
事件属性为嵌套结构；需仔细解析

3. Manage Feature Flags

3. 管理功能标志

When to use: User wants to create, view, or manage feature flags

Tool sequence:

POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS

- List existing feature flags [Required]

```
POSTHOG_RETRIEVE_FEATURE_FLAG_DETAILS
```
- Get detailed flag configuration [Optional]

POSTHOG_CREATE_FEATURE_FLAGS_FOR_PROJECT

- Create a new feature flag [Optional]

Key parameters:

For listing:
```
project_id
```
(required)
For details:
```
project_id
```
,
```
id
```
(feature flag ID)
For creation:
- ```
project_id
```
  : Target project
- ```
key
```
  : Flag key (e.g., 'new-dashboard-beta')
- ```
name
```
  : Human-readable name
- ```
filters
```
  : Targeting rules and rollout percentage
- ```
active
```
  : Whether the flag is enabled

Pitfalls:

Feature flag
```
key
```
must be unique within a project
Flag keys should use kebab-case (e.g., 'my-feature-flag')
```
filters
```
define targeting groups with properties and rollout percentages
Creating a flag with
```
active: true
```
immediately enables it for matching users
Flag changes take effect within seconds due to PostHog's polling mechanism

适用场景：用户需要创建、查看或管理功能标志

工具调用流程：

POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS

- 列出现有功能标志 [必填]

```
POSTHOG_RETRIEVE_FEATURE_FLAG_DETAILS
```
- 获取标志的详细配置 [可选]

POSTHOG_CREATE_FEATURE_FLAGS_FOR_PROJECT

- 创建新的功能标志 [可选]

关键参数：

列出标志：
```
project_id
```
（必填）
获取详情：
```
project_id
```
、
```
id
```
（功能标志ID）
创建标志：
- ```
project_id
```
  ：目标项目
- ```
key
```
  ：标志键（例如：'new-dashboard-beta'）
- ```
name
```
  ：人类可读的名称
- ```
filters
```
  ：目标规则与发布百分比
- ```
active
```
  ：标志是否启用

注意事项：

功能标志的
```
key
```
在项目内必须唯一
标志键应使用短横线分隔命名（例如：'my-feature-flag'）
```
filters
```
通过属性和发布百分比定义目标用户组
创建时设置
```
active: true
```
会立即对匹配的用户启用该标志
由于PostHog的轮询机制，标志更改会在几秒内生效

4. Manage Projects

4. 管理项目

When to use: User wants to list or inspect PostHog projects and organizations

Tool sequence:

POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION

- List all projects [Required]

Key parameters:

```
organization_id
```
: Organization identifier (may be optional depending on auth)
```
limit
```
: Number of results per page
```
offset
```
: Pagination offset

Pitfalls:

Project IDs are numeric; used as parameters in most other endpoints
Organization ID may be required; check your PostHog setup
Pagination is offset-based; iterate until results are empty
Project settings include API keys and configuration details

适用场景：用户需要列出或查看PostHog项目与组织信息

工具调用流程：

POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION

- 列出所有项目 [必填]

关键参数：

```
organization_id
```
：组织标识符（根据身份验证方式可能为可选）
```
limit
```
：每页结果数量
```
offset
```
：分页偏移量

注意事项：

项目ID为数字；是大多数其他接口的必填参数
可能需要组织ID；请检查你的PostHog设置
分页基于偏移量；需循环调用直到结果为空
项目设置包含API密钥与配置详情

5. User Profile and Authentication

5. 用户配置文件与身份验证

When to use: User wants to check current user details or verify API access

Tool sequence:

```
POSTHOG_WHOAMI
```
- Get current API user information [Optional]
```
POSTHOG_RETRIEVE_CURRENT_USER_PROFILE
```
- Get detailed user profile [Optional]

Key parameters:

No required parameters for either call
Returns current authenticated user's details, permissions, and organization info

Pitfalls:

WHOAMI is a lightweight check; use for verifying API connectivity
User profile includes organization membership and permissions
These endpoints confirm the API key's access level and scope

适用场景：用户需要查看当前用户详情或验证API访问权限

工具调用流程：

```
POSTHOG_WHOAMI
```
- 获取当前API用户信息 [可选]
```
POSTHOG_RETRIEVE_CURRENT_USER_PROFILE
```
- 获取详细用户配置文件 [可选]

关键参数：

两个调用均无必填参数
返回当前已认证用户的详情、权限与组织信息

注意事项：

WHOAMI是轻量级检查；用于验证API连通性
用户配置文件包含组织成员身份与权限信息
这些接口可确认API密钥的访问级别与范围

Common Patterns

常见模式

ID Resolution

ID解析

Organization -> Project ID:

1. Call POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION
2. Find project by name in results
3. Extract id (numeric) for use in other endpoints

Feature flag name -> Flag ID:

1. Call POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS with project_id
2. Find flag by key or name
3. Extract id for detailed operations

组织 -> 项目ID：

1. 调用POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION
2. 在结果中按名称查找项目
3. 提取id（数字）用于其他接口

功能标志名称 -> 标志ID：

1. 使用project_id调用POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS
2. 按key或名称查找标志
3. 提取id用于详细操作

Feature Flag Targeting

功能标志目标定位

Feature flags support sophisticated targeting:

json

{
  "filters": {
    "groups": [
      {
        "properties": [
          {"key": "email", "value": "@company.com", "operator": "icontains"}
        ],
        "rollout_percentage": 100
      },
      {
        "properties": [],
        "rollout_percentage": 10
      }
    ]
  }
}

Groups are evaluated in order; first matching group determines the rollout
Properties filter users by their traits
Rollout percentage determines what fraction of matching users see the flag

功能标志支持复杂的目标定位：

json

{
  "filters": {
    "groups": [
      {
        "properties": [
          {"key": "email", "value": "@company.com", "operator": "icontains"}
        ],
        "rollout_percentage": 100
      },
      {
        "properties": [],
        "rollout_percentage": 10
      }
    ]
  }
}

用户组按顺序评估；第一个匹配的组决定发布范围
属性用于根据用户特征筛选用户
发布百分比决定匹配用户中能看到该标志的比例

Pagination

分页

Events: Use
```
offset
```
and
```
limit
```
(offset-based)
Feature flags: Use
```
offset
```
and
```
limit
```
(offset-based)
Projects: Use
```
offset
```
and
```
limit
```
(offset-based)
Continue until results array is empty or smaller than
```
limit
```

事件：使用
```
offset
```
和
```
limit
```
（基于偏移量）
功能标志：使用
```
offset
```
和
```
limit
```
（基于偏移量）
项目：使用
```
offset
```
和
```
limit
```
（基于偏移量）
持续调用直到结果数组为空或数量少于
```
limit
```

Known Pitfalls

已知注意事项

Project IDs:

Required for most API endpoints
Always resolve project names to numeric IDs first
Multiple projects can exist in one organization

Event Naming:

System events use
```
$
```
prefix ($pageview, $identify, $autocapture)
Custom events should NOT use
```
$
```
prefix
Event names are case-sensitive; maintain consistency

Feature Flags:

Flag keys must be unique within a project
Use kebab-case for flag keys
Changes propagate within seconds
Deleting a flag is permanent; consider disabling instead

Rate Limits:

Event ingestion has throughput limits
Batch events where possible for efficiency
API endpoints have per-minute rate limits

Response Parsing:

Response data may be nested under
```
data
```
or
```
results
```
key
Paginated responses include
```
count
```
,
```
next
```
,
```
previous
```
fields
Event properties are nested objects; access carefully
Parse defensively with fallbacks for optional fields

项目ID：

大多数API接口必填
请始终先将项目名称解析为数字ID
一个组织下可存在多个项目

事件命名：

系统事件使用
```
$
```
前缀（$pageview、$identify、$autocapture）
自定义事件不得使用
```
$
```
前缀
事件名称区分大小写；需保持一致性

功能标志：

标志键在项目内必须唯一
标志键使用短横线分隔命名
更改会在几秒内生效
删除标志是永久性操作；建议改为禁用

速率限制：

事件摄入有吞吐量限制
尽可能批量发送事件以提高效率
API接口有每分钟调用次数限制

响应解析：

响应数据可能嵌套在
```
data
```
或
```
results
```
键下
分页响应包含
```
count
```
、
```
next
```
、
```
previous
```
字段
事件属性为嵌套对象；需谨慎访问
解析时需为可选字段设置回退逻辑

Quick Reference

快速参考

Task	Tool Slug	Key Params
Capture event	POSTHOG_CAPTURE_EVENT	event, distinct_id, properties
List events	POSTHOG_LIST_AND_FILTER_PROJECT_EVENTS	project_id, event, after, before
List feature flags	POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS	project_id
Get flag details	POSTHOG_RETRIEVE_FEATURE_FLAG_DETAILS	project_id, id
Create flag	POSTHOG_CREATE_FEATURE_FLAGS_FOR_PROJECT	project_id, key, filters
List projects	POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION	organization_id
Who am I	POSTHOG_WHOAMI	(none)
User profile	POSTHOG_RETRIEVE_CURRENT_USER_PROFILE	(none)

Powered by Composio

任务	工具标识	关键参数
捕获事件	POSTHOG_CAPTURE_EVENT	event, distinct_id, properties
列出事件	POSTHOG_LIST_AND_FILTER_PROJECT_EVENTS	project_id, event, after, before
列出功能标志	POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS	project_id
获取标志详情	POSTHOG_RETRIEVE_FEATURE_FLAG_DETAILS	project_id, id
创建标志	POSTHOG_CREATE_FEATURE_FLAGS_FOR_PROJECT	project_id, key, filters
列出项目	POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION	organization_id
验证身份	POSTHOG_WHOAMI	(无)
用户配置文件	POSTHOG_RETRIEVE_CURRENT_USER_PROFILE	(无)

由Composio提供支持